376 lines
6.8 KiB
Markdown
376 lines
6.8 KiB
Markdown
# 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.
|