From f47fea5d6f5829183b2d0f5b72d6f9815054f1f2 Mon Sep 17 00:00:00 2001 From: phaichayon Date: Tue, 7 Jul 2026 19:46:31 +0700 Subject: [PATCH] commit eng0 --- ...eng.0-engineering-governance-2026-07-07.md | 70 ++ docs/standards/engineering-constitution.md | 701 ++++++++++++++++++ plans/task-eng.0.md | 375 ++++++++++ 3 files changed, 1146 insertions(+) create mode 100644 docs/implementation/task-eng.0-engineering-governance-2026-07-07.md create mode 100644 docs/standards/engineering-constitution.md create mode 100644 plans/task-eng.0.md diff --git a/docs/implementation/task-eng.0-engineering-governance-2026-07-07.md b/docs/implementation/task-eng.0-engineering-governance-2026-07-07.md new file mode 100644 index 0000000..a37ed9a --- /dev/null +++ b/docs/implementation/task-eng.0-engineering-governance-2026-07-07.md @@ -0,0 +1,70 @@ +# Task ENG.0 Implementation Report - 2026-07-07 + +## Scope + +- start and complete the documentation-only Engineering Governance phase +- review business, architecture, UI, standards, security, and current implementation patterns already frozen by BU-R and AR work +- produce the official engineering governance baseline for future implementation tasks + +## Review Summary + +Reviewed before drafting: + +- `AGENTS.md` +- `plans/task-eng.0.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` +- `layout.md` +- `docs/security/crm-authorization-boundaries.md` +- `docs/business/relationship-sales-workspace-blueprint-v1.md` +- `docs/implementation/task-bu-r.0-business-blueprint-freeze-2026-07-07.md` +- `docs/implementation/task-bu-r.0.1-workspace-activity-business-blueprint-2026-07-07.md` +- `docs/implementation/task-bu-r.1-business-capability-audit-2026-07-07.md` +- `docs/implementation/task-ar.1-architecture-transition-plan-2026-07-07.md` +- `docs/implementation/task-ar.2-epic-technical-design-2026-07-07.md` +- `docs/implementation/task-ar.2-workspace-ui-ux-design-note-2026-07-07.md` +- `src/lib/auth/session.ts` +- `src/lib/auth/crm-access.ts` +- representative route/service/foundation patterns under: + - `src/app/api/crm/**` + - `src/features/crm/customers/**` + - `src/features/products/**` + - `src/features/users/**` + - `src/features/foundation/audit-log/**` + - `src/features/foundation/approval/**` + - `src/features/foundation/storage/**` + +## What Was Produced + +- official engineering governance baseline: + + `docs/standards/engineering-constitution.md` + +## Key Decisions Captured + +1. ENG.0 freezes review-first and reuse-first implementation as mandatory, not optional advice. +2. Feature ownership, service boundaries, Route Handler patterns, and projection rules now follow one documented model aligned with current repo structure. +3. Business logic remains service-owned; projections remain read-only; route handlers remain thin. +4. Security enforcement is frozen around resolved CRM access, server-side scope enforcement, and pricing visibility checks. +5. UI implementation is frozen to existing dashboard shell, `PageContainer`, shadcn/ui reuse, and no-code-before-design for major new workspace surfaces. +6. Database, testing, delivery, AI implementation, and code review expectations are now documented in one standards file future tasks can cite directly. +7. Preserve -> Extend -> Controlled Refactor -> Replace is frozen as the engineering decision matrix for change strategy. + +## Verification + +- Documentation-only change. +- No schema, migration, API, service, UI, permission, or runtime business-logic files changed production behavior. +- No build or test command was required for this phase. + +## Outcome + +ENG.0 now gives ALLA OS an explicit Engineering Constitution aligned with: + +- Business Constitution (`BU-R.0`, `BU-R.0.1`, `BU-R.1`) +- Architecture Constitution (`AR.1`, `AR.2`) +- Workspace UI Constitution +- current foundations and production code patterns already present in the repository diff --git a/docs/standards/engineering-constitution.md b/docs/standards/engineering-constitution.md new file mode 100644 index 0000000..d25c214 --- /dev/null +++ b/docs/standards/engineering-constitution.md @@ -0,0 +1,701 @@ +# Engineering Constitution + +This document freezes the engineering governance for ALLA OS after the Business Constitution (`BU-R.0`, `BU-R.0.1`, `BU-R.1`), Architecture Constitution (`AR.1`, `AR.2`), and Workspace UI Constitution are in place. + +It defines how future implementation work must be designed, coded, reviewed, tested, and delivered. + +--- + +## 1. Purpose and Precedence + +### Purpose + +- keep implementation aligned with the Relationship-Driven Sales Workspace blueprint +- preserve current production foundations while enabling controlled extension +- prevent duplicate services, APIs, projections, UI systems, and business logic +- give engineers and AI agents one shared delivery model + +### Governance precedence + +Future work must follow this order: + +1. business constitution and business blueprint documents +2. architecture transition and epic technical design documents +3. this Engineering Constitution +4. workspace UI/UX governance +5. existing approved foundations and feature implementations + +If two sources conflict, the higher item in this list wins unless a newer accepted ADR explicitly replaces it. + +### Mandatory inputs before implementation + +Every implementation task must review: + +- `AGENTS.md` +- `docs/standards/project-foundations.md` +- `docs/standards/architecture-rules.md` +- `docs/standards/ui-ux-rules.md` +- `docs/standards/task-review-checklist.md` +- `docs/standards/task-catalog.md` +- relevant `docs/adr/**` +- relevant `docs/business/**` +- relevant `docs/security/**` +- relevant `docs/implementation/**` +- relevant existing foundations under `src/features/foundation/**` +- relevant existing feature implementations under `src/features/**` + +No implementation may bypass this review-first rule. + +--- + +## 2. Feature Architecture Rules + +### Feature ownership model + +- each domain or shared capability must have one owning feature or foundation +- route handlers are HTTP boundaries, not business owners +- shared cross-cutting behavior must live in a foundation before a second feature reimplements it +- new CRM work must extend `src/features/crm/**` or `src/features/foundation/**` instead of creating parallel top-level domains + +### Approved feature structure + +Default structure for app-owned features: + +```text +src/features// + api/ + types.ts + service.ts + queries.ts + mutations.ts + components/ + schemas/ + server/ +``` + +Allowed additions when justified: + +- `adapters/` for migration seams or projection adapters +- `lib/` for feature-local pure helpers +- `constants/` for feature-local stable constants +- `hooks/` for feature-local client hooks + +### Layer responsibilities + +- `api/types.ts`: public TypeScript contracts for UI and service consumers +- `api/service.ts`: client-facing API client wrappers only +- `api/queries.ts`: React Query key factories and query options +- `api/mutations.ts`: centralized mutation configs and invalidation behavior +- `components/`: UI composition only +- `schemas/`: request payload validation and form schemas +- `server/`: business logic, persistence orchestration, scope enforcement, data shaping + +### Public and internal modules + +- only `api/**`, `components/**`, and explicitly shared helpers are public to outside consumers +- `server/**` is internal to the owning feature unless consciously reused by another server-side feature +- client components must not import database or server-only modules +- cross-feature imports should target stable public contracts, not incidental internals + +### Shared module rules + +- shared UI belongs in `src/components/**` or an approved foundation/shared area +- shared business logic belongs in the owning foundation or feature server layer +- do not create shared modules only to avoid choosing ownership + +### Cross-feature dependency rules + +Allowed direction: + +- app routes -> feature API/services/components +- route handlers -> auth/session/validation -> owning feature server services +- feature server services -> foundations and lower-level shared security/utilities +- projections/read models -> source services or approved dataset layers + +Forbidden direction: + +- source domains depending on projection-only domains for write behavior +- features reaching directly into another feature's UI internals +- client code importing Drizzle, server-only services, or auth enforcement modules +- projection code becoming the write owner of business lifecycle state + +### Feature registration rule + +Before creating a new feature, confirm that the need cannot be satisfied by extending: + +- an existing CRM feature +- an existing foundation +- an existing report, approval, PDF, storage, audit, or security layer + +If a new feature is still required, document why reuse was insufficient. + +--- + +## 3. Service Layer Standards + +### Service composition + +The service layer owns business rules. It may be split into: + +- business services +- query services +- projection services +- application/orchestration services +- domain-specific helper adapters + +### Frozen service rules + +- route handlers stay thin +- services own business lifecycle rules +- services enforce server-side scope, pricing visibility, and permission-sensitive behavior +- services may call foundations and approved sibling services when reuse is explicit +- services must not contain UI concerns +- services must not authorize with raw role strings alone + +### Business ownership boundaries + +- `Customer` owns relationship anchor behavior +- `Lead` owns early demand signal behavior +- `Opportunity` owns project pursuit and won/lost outcome behavior +- `Quotation` owns commercial document lifecycle +- `Approval` owns approval workflow execution +- future `Activity` owns shared operational work records +- `Timeline`, `Calendar`, `My Day`, `Manager`, and `Executive` are read-model or workspace consumers, not primary write owners + +### Transaction boundary rules + +- one service owns the transaction for one business mutation +- downstream side effects such as audit logging, notifications, event publishing, or artifact updates must happen from the owning service flow +- avoid multi-route, UI-driven orchestration for business-critical mutations + +### Query and projection service rules + +- query services return read-ready data and may combine multiple foundations +- projection services are read-only and rebuildable +- projection services must not become hidden write paths +- report services must reuse the report foundation dataset and builder layers + +### Internal repository rule + +This repo does not use a heavyweight repository architecture. + +Allowed pattern: + +- lightweight persistence helpers or adapters inside `server/` +- Drizzle queries close to the owning service + +Forbidden pattern: + +- introducing a parallel abstract repository layer across the app without a project-level decision + +--- + +## 4. Repository and Persistence Standards + +### Ownership + +- each table or schema area must have a clear owning feature or foundation +- only the owning server service should perform write orchestration for its tables +- cross-feature readers should prefer owning services or approved read models before querying tables directly + +### Persistence rules + +- use Drizzle ORM for database access +- keep SQL and query composition inside server services or approved dataset modules +- reuse existing dataset and export services for reporting work +- do not move domain logic into route handlers just because Drizzle is easy to call there + +### Backward compatibility + +- preserve existing production contracts while extending them +- use additive migration patterns first +- dual-read or adapter-first strategies are preferred for high-risk transitions such as Activity and projection work + +--- + +## 5. API Standards + +### Boundary + +- Route Handlers under `src/app/api/**` are the default HTTP boundary +- new CRM APIs belong under `/api/crm/**` +- settings or foundation APIs belong under their existing route families + +### Route handler contract + +Every route handler should: + +1. require session or organization access +2. validate permissions +3. parse and validate request input +4. build access/security context when needed +5. call the owning server service +6. map response +7. log audit or security events where applicable + +### Naming and path rules + +- use plural resource names for collection routes +- use nested child routes only when the child lifecycle is truly parent-scoped +- use action routes only for explicit domain transitions such as `mark-won`, `submit-approval`, `complete`, `cancel` +- avoid generic verb-heavy route families when a resource-oriented route can express the behavior + +### Validation + +- use Zod for request validation at the boundary +- reuse feature schemas where possible +- validation error messages should be business-readable and not leak backend detail + +### Response rules + +- preserve current stable contract shapes inside an existing route family +- new routes should prefer predictable JSON responses with clear success, data, and meta sections when not constrained by an existing family +- list routes should return pagination metadata when pagination exists +- API responses must remain ISO-8601 UTC for datetime fields + +### Authorization + +- use `requireSession()`, `requireSystemRole()`, or `requireOrganizationAccess()` +- CRM routes must apply resolved CRM access and scope enforcement +- UI visibility never replaces server authorization + +### Filtering, sorting, and search + +- filters should be explicit, typed, and documented in feature contracts +- use URL-driven filter state for shareable list screens +- keep filtering semantics aligned between on-screen data and exports + +### Versioning strategy + +- preserve compatible route contracts whenever possible +- prefer additive fields and child routes over breaking replacements +- introduce a new route shape only when compatibility cannot be preserved cleanly + +--- + +## 6. Business Event, Projection, and Timeline Rules + +### Event philosophy + +- business events are immutable facts emitted after successful state changes +- events are not a replacement for audit logs +- events may fan out to timeline, calendar, dashboard, notification, reminder, or future automation + +### Publisher ownership + +- source-domain services publish their own events +- do not centralize event publishing in UI or ad hoc route helpers +- preserve current approval notification compatibility while expanding the event model + +### Event contract rules + +- use lowercase dot-separated event names +- include `schemaVersion` +- include organization, entity, actor, primary record, related records, and visibility context +- event payloads must avoid leaking pricing-sensitive or unauthorized commercial data + +### Projection rules + +- `Timeline` and `Calendar` are generated projections only +- projections are read-only and rebuildable +- projections never own lifecycle state +- phase 1 projection services should favor query-time generation or cacheable read models before new authoritative tables + +### Projection ownership + +- activity projections belong to the Activity and projection layers +- milestone projections remain owned by their source domain semantics +- dashboard and reports consume projections or source datasets but do not become source-of-truth mutations + +### Idempotency and dedupe + +- event publication and subscribers must support safe retry behavior +- notification or projection consumers must guard against duplicate fan-out +- approval events require extra care because notification publishing already exists + +--- + +## 7. UI Engineering Rules + +### Required UI inputs + +All user-facing work must review: + +- `layout.md` +- `docs/standards/ui-ux-rules.md` +- relevant business terminology docs +- nearby production screens in the same route family + +Major workspace surfaces must also reference: + +- `BU-R.0` +- `BU-R.0.1` +- `BU-R.1` +- `AR.1` +- `AR.2` +- the latest workspace UI/UX design note + +### Frozen UI rules + +- preserve the existing dashboard shell +- use `PageContainer` for dashboard page framing +- reuse shadcn/ui primitives and app wrappers +- reuse existing table, form, filter, dialog, sheet, badge, and status patterns before creating new ones +- new business-role workspaces live under `/dashboard/crm/*`, not `/dashboard/workspaces` +- no code-first implementation for major new workspace surfaces without an approved design note + +### Data and state rules + +- server components first +- use React Query for server-state fetching +- use server prefetch plus `HydrationBoundary` for data-heavy app pages +- use `nuqs` for shareable URL state +- use TanStack Form plus Zod for new forms + +### UX state rules + +Every surface must define: + +- loading states +- empty states +- error states +- disabled and pending action states +- permission-aware visibility behavior +- responsive behavior + +### Accessibility rules + +- semantic controls and accessible names are required +- keyboard navigation must remain usable for tables, dialogs, sheets, tabs, and menus +- focus behavior must be predictable +- status cannot be conveyed by color alone + +--- + +## 8. Code Quality Standards + +### Naming + +- use business terms frozen by the business and architecture constitutions +- keep active production terminology aligned with `opportunity`, not historical `enquiry`, unless touching historical-only documentation +- use clear, explicit function and file names over vague generic helpers + +### File and folder naming + +- keep file names lowercase kebab-case unless a framework convention requires otherwise +- use stable feature-local names such as `service.ts`, `queries.ts`, `mutations.ts`, `types.ts` +- avoid creating near-duplicate files with ambiguous suffixes like `service2`, `new`, or `final` + +### TypeScript rules + +- strict typing is required +- avoid `any` +- define public contracts explicitly in `api/types.ts` or equivalent shared contracts +- keep server-only and client-safe types clearly separated when necessary + +### Error handling + +- expected business or authorization failures should produce explicit typed or status-aware errors +- do not leak SQL or infrastructure internals to business-facing surfaces +- centralize reusable failure behavior where patterns already exist + +### Logging and audit + +- use the audit foundation for business mutations, exports, and sensitive denials +- use ordinary console logging only for operational debugging or unexpected failures +- logs must not become a substitute for governed audit events + +### Validation + +- validate at the boundary +- revalidate critical business invariants inside services when necessary +- do not trust client-side validation alone + +### Comments + +- comments should explain non-obvious business or security rules +- avoid comments that restate the code + +### Technical debt policy + +- prefer preserve -> extend -> controlled refactor -> replace +- small cleanup is encouraged when it improves safety or clarity +- unrelated rewrites are prohibited + +--- + +## 9. Database and Migration Standards + +### Migration strategy + +- additive, backward-compatible migrations are preferred +- schema changes must preserve current production behavior until replacement paths are proven +- high-risk data model changes must document migration and coexistence strategy first + +### Schema ownership + +- schema changes must be owned by the relevant feature or foundation +- projection schemas, if introduced later, must remain clearly separate from source-of-truth tables + +### Rollback strategy + +- every risky migration must define rollback or safe-disable behavior +- do not require emergency manual data surgery as the normal rollback path + +### Seed strategy + +- foundation seeds remain the source for governed options and bootstrap records where already used +- new seed data must be deterministic and documented + +### Explicit non-changes rule + +Documentation-only tasks must not silently modify schema, migrations, or runtime persistence behavior. + +--- + +## 10. Testing Standards + +### Minimum testing lens + +Each implementation must define the right mix of: + +- unit tests +- service tests +- route handler or API tests +- permission and scope tests +- projection and event tests where applicable +- regression tests for preserved behavior +- manual verification scenarios + +### Required test themes + +- happy path behavior +- permission denial behavior +- scope enforcement behavior +- pricing visibility behavior for quotation-derived outputs +- audit/event side effects when applicable +- cache freshness after CRUD mutations + +### Projection and event testing + +- timeline and calendar work must verify ordering, filtering, visibility, and dedupe behavior +- event-driven work must verify idempotency and compatibility with existing notification flows + +### UAT checklist baseline + +- loading state visible +- empty state helpful +- error state actionable +- successful mutation refreshes the affected UI without manual browser refresh +- mobile and desktop layouts remain usable + +--- + +## 11. Delivery Rules + +### Epic lifecycle + +Each epic must define: + +- objective +- non-goals +- reviewed history and foundations +- API and service boundaries +- security and pricing rules +- audit and event behavior +- verification plan +- rollout and rollback notes when risk is non-trivial + +### Feature lifecycle + +For feature implementation: + +1. review requirements and historical context +2. identify reuse targets +3. confirm architecture and security boundaries +4. define smallest viable extension +5. implement in the owning layer +6. self-review architecture, UI, data freshness, and security +7. validate +8. document results + +### Review gates + +- architecture review +- business rule review +- security and permission review +- UI consistency review for user-facing work +- regression and backward-compatibility review + +### Release and rollback baseline + +- document migrations and toggles when present +- document impacted routes or surfaces +- document known compatibility seams +- document rollback or safe-disable path for non-trivial changes + +--- + +## 12. Definition of Done + +### Feature + +- required review completed +- foundations reused or non-reuse rationale documented +- implementation stays within approved architecture +- permissions, scope, and pricing visibility enforced server-side where applicable +- audit and event behavior handled where required +- loading, empty, error, disabled, and success states covered for user-facing work +- validation completed and recorded +- documentation updated if governance or reusable patterns changed + +### Epic + +- feature-level done conditions met for each delivered slice +- sequence and dependency assumptions remain compatible with `AR.2` +- cross-feature duplication was not introduced +- migration or rollout notes recorded for future slices + +### Bug Fix + +- root cause identified +- fix scoped to the owning layer +- regression risk checked +- validation performed against the failing scenario + +### Refactor + +- ownership and behavior preserved unless explicitly approved otherwise +- backward compatibility risks documented +- no unrelated behavior churn introduced + +--- + +## 13. AI Engineering Rules + +AI contributors must follow the same governance as human contributors. + +### Mandatory AI rules + +- review before implementation +- reuse before creation +- preserve before refactor +- never duplicate business logic, lifecycle logic, projection logic, or permission logic +- identify existing services, routes, and components before adding new ones +- keep route handlers thin +- keep business logic in services +- keep projections read-only +- record assumptions and validation results + +### AI implementation checklist + +Before writing code, confirm: + +- business constitution reviewed +- architecture constitution reviewed +- engineering constitution reviewed +- workspace UI constitution reviewed when UI is involved +- relevant ADRs reviewed +- related implementation history reviewed +- relevant foundations inspected +- existing pattern search completed +- reuse plan chosen +- validation plan defined + +--- + +## 14. Code Review Checklist + +### Architecture + +- does the change extend the right owning feature or foundation? +- does it avoid parallel services, APIs, or UI systems? +- does it preserve route-handler-thin and service-owned business logic? + +### Business + +- does it follow frozen domain ownership and terminology? +- does it avoid moving responsibility into the wrong layer? + +### Security + +- are permission, scope, and pricing rules enforced server-side? +- are raw role-string checks avoided? +- are denials audited when needed? + +### Performance and data freshness + +- are query keys and invalidation complete? +- are projections or datasets using the approved read paths? +- does the UI refresh correctly after mutation? + +### Accessibility and UI consistency + +- does the surface reuse approved page, table, form, dialog, and state patterns? +- are loading, empty, error, and responsive states covered? + +### Maintainability and backward compatibility + +- are contracts explicit? +- does the change avoid hidden coupling and duplicate logic? +- are compatibility seams, rollout notes, or follow-up risks documented? + +--- + +## 15. Engineering Decision Matrix + +Use this matrix before choosing implementation strategy. + +### Preserve + +Use when: + +- the existing module already owns the behavior +- the change is additive or corrective +- replacement would create unnecessary migration risk + +### Extend + +Use when: + +- the existing module is the correct owner +- new capability fits the current architecture +- a controlled addition avoids parallel systems + +### Controlled Refactor + +Use when: + +- current ownership is correct but the structure blocks safe extension +- refactor reduces duplication or clarifies a reusable seam +- compatibility can be preserved during the change + +### Replace + +Use only when: + +- preserve, extend, and controlled refactor are insufficient +- replacement rationale is explicit +- migration and rollback strategy are documented +- governance review accepts the risk + +### Explicit rule + +If a task cannot explain why it is preserving, extending, refactoring, or replacing, it is not ready for implementation. + +--- + +## 16. Official ENG.0 Outcome + +ENG.0 freezes one engineering model for future ALLA OS implementation: + +- review-first +- reuse-first +- service-owned business logic +- route-handler-thin API boundaries +- resolved-access security enforcement +- projection-as-read-model, not source-of-truth +- shared UI shell preservation +- explicit validation, audit, and delivery discipline + +No future implementation epic may bypass this constitution. diff --git a/plans/task-eng.0.md b/plans/task-eng.0.md new file mode 100644 index 0000000..5371b09 --- /dev/null +++ b/plans/task-eng.0.md @@ -0,0 +1,375 @@ +# Task ENG.0 - Engineering Governance & Delivery Rules + +Status: Completed +Priority: Critical +Type: Engineering Governance / Technical Standards + +Depends On + +- BU-R.0 Business Constitution +- BU-R.0.1 Workspace & Activity Blueprint +- BU-R.1 Business Capability Audit +- AR.1 Architecture Transition Plan +- AR.2 Epic & Technical Design +- AR.2 Workspace UI/UX Design Note + +--- + +# Objective + +Establish the official engineering governance for ALLA OS. + +This task defines how future implementation work must be designed, coded, reviewed, tested, and delivered while preserving the approved Business Constitution, Architecture Constitution, and UI Constitution. + +The objective is to ensure every implementation follows the same engineering standards regardless of whether the contributor is a human developer or an AI agent. + +--- + +# Background + +Business architecture and transition architecture are now complete. Future work shifts from architecture planning into implementation delivery. + +Without engineering governance, future implementations may diverge in: + +- folder structure +- service composition +- API contracts +- projection implementation +- event handling +- UI composition +- testing +- migration +- code quality + +ENG.0 freezes the engineering rules before implementation begins. + +--- + +# Review Required + +Review before producing governance. + +Business + +- Relationship & Sales Workspace Blueprint +- Business Capability Audit + +Architecture + +- Architecture Transition Plan +- Epic Technical Design + +UI + +- Workspace UI/UX Design Note +- `layout.md` +- `ui-ux-rules.md` +- `ui-ux-pro-max` guidance + +Codebase + +- `AGENTS.md` +- `project-foundations.md` +- `architecture-rules.md` +- `task-review-checklist.md` +- existing feature folder conventions +- current shared UI components +- current service layer +- repository layer +- existing API patterns +- permission model +- audit logging +- storage +- approval engine + +--- + +# Scope + +## Part 1 - Feature Architecture Rules + +Freeze: + +- feature folder convention +- layer responsibilities +- public API boundary +- internal modules +- shared modules +- cross-feature dependency rules +- feature registration +- import rules +- dependency direction +- allowed dependency graph +- forbidden dependency graph + +## Part 2 - Service Layer Rules + +Freeze: + +- service composition +- business services +- query services +- projection services +- application services +- domain services +- shared services +- allowed service interaction +- business ownership +- transaction boundary + +## Part 3 - Repository Standards + +Freeze: + +- persistence ownership +- internal repository expectations +- Drizzle placement rules +- cross-feature persistence access rules + +## Part 4 - API Rules + +Freeze: + +- REST conventions +- request validation +- response format +- error handling +- authorization +- pagination +- filtering +- sorting +- search +- versioning strategy +- API naming + +## Part 5 - Event & Projection Rules + +Freeze: + +- business event +- domain event +- projection builder +- timeline projection +- calendar projection +- dashboard projection +- notification projection +- projection ownership +- event publishing +- event subscription +- idempotency + +## Part 6 - UI Engineering Rules + +UI implementation must: + +- review `layout.md` +- review `ui-ux-rules.md` +- review the Workspace UI/UX Design Note +- use `ui-ux-pro-max` +- use the existing shadcn/ui component library + +Determine: + +- page composition +- workspace composition +- component composition +- state management +- form strategy +- dialog strategy +- drawer strategy +- accessibility +- responsive strategy +- loading strategy +- empty state +- permission-aware rendering + +No implementation may redesign the existing CRM shell without architectural approval. + +## Part 7 - Code Quality Rules + +Freeze: + +- naming conventions +- file naming +- folder naming +- TypeScript conventions +- error handling +- logging +- validation +- code comments +- reusable utilities +- technical debt policy + +## Part 8 - Database & Migration Rules + +Freeze: + +- migration strategy +- backward compatibility migration +- schema ownership +- projection schema +- rollback strategy +- seed strategy + +## Part 9 - Testing Rules + +Freeze: + +- unit test +- integration test +- API test +- permission test +- projection test +- event test +- regression test +- UAT checklist +- definition done + +## Part 10 - Delivery Rules + +Freeze: + +- epic lifecycle +- feature lifecycle +- review checklist +- architecture validation +- business validation +- UI validation +- testing +- migration +- release checklist +- rollback checklist + +## Part 11 - AI Engineering Rules + +Define how AI contributors must work. + +Every implementation task must: + +- review Business Constitution +- review Architecture Constitution +- review Engineering Constitution +- review Workspace UI Constitution +- review existing implementation first +- reuse existing modules whenever possible + +Preferred change strategy: + +- Preserve +- Extend +- Controlled Refactor +- Replace + +Never: + +- duplicate business logic +- duplicate business lifecycle +- duplicate projection logic + +Always identify existing reusable services before creating new code. + +--- + +# Deliverables + +Produce: + +## 1 Engineering Constitution + +## 2 Feature Architecture Rules + +## 3 Service Layer Standards + +## 4 Repository Standards + +## 5 API Standards + +## 6 Business Event Engineering & Quality Standards + +## 7 UI Engineering Rules + +## 8 Code Quality Standards + +## 9 Database & Migration Standards + +## 10 Testing Standards + +## 11 Definition Done for Feature, Epic, Bug Fix, Refactor + +## 12 AI Implementation Checklist + +Checklist implementation tasks must complete before writing code. + +## 13 Code Review Checklist + +- Architecture +- Business +- Security +- Performance +- Accessibility +- Maintainability +- Backward Compatibility +- UI Consistency + +## 14 Engineering Decision Matrix + +Classify implementation decisions as: + +- Preserve +- Extend +- Refactor +- Replace + +with architectural justification. + +--- + +# Constraints + +Documentation only. + +DO NOT: + +- modify schema +- modify migrations +- modify APIs +- modify services +- modify UI +- modify permissions +- modify runtime logic + +No production implementation. + +--- + +# Success Criteria + +Engineering standards fully documented. +Every future implementation follows one engineering model. +Feature development becomes predictable. +Business Constitution, Architecture Constitution, Engineering Constitution, and UI Constitution stay aligned. +The project is ready for implementation epics. + +--- + +# Output + +- `docs/standards/engineering-constitution.md` +- `docs/implementation/task-eng.0-engineering-governance-2026-07-07.md` + +--- + +# Engineering Governance Rule + +Every future implementation epic must explicitly reference: + +- Business Constitution (`BU-R.0` / `BU-R.0.1`) +- Business Capability Audit (`BU-R.1`) +- Architecture Transition Plan (`AR.1`) +- Epic Technical Design (`AR.2`) +- Workspace UI/UX Design Note (`AR.2`) +- Engineering Constitution (`ENG.0`) + +before implementation begins. + +No implementation may bypass governance documents.