alla-allaos-fullstack/plans/task-eng.0.md

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.