# Progress Tracker Template (templates/tpl-progress.md)

> **Used by:** step-05-deploy (section 4: Generate progress.txt)
> **Purpose:** Template structure for .ralph/progress.txt - populate with module-specific data

## Template

```
═════════════════════════════════════════════════════════════════
  SMARTSTACK RALPH LOOP - PROGRESS TRACKER
  Project: {project_name} | Application: {app_name}
  Modules: {count} ({moduleOrder.join(', ')})
  Strategy: {implementation_strategy}
  Created: {timestamp}
  Status: HANDED-OFF
═════════════════════════════════════════════════════════════════

{For each module in topological order:}
[MODULE: {module_name}] ({complexity})
  Status: NOT STARTED
  Dependencies: {list of module dependencies or "FOUNDATION"}

  [DOMAIN] Entity & Value Object Definitions
    □ Define {Entity1} entity with properties and validation
    □ Define {Entity2} entity with relationships
    □ Define {ValueObject1} value object
    □ Define domain exceptions
    □ Total: X tasks

  [SEEDDATA-CORE] Core Configuration (MANDATORY)
    □ NavigationApplicationSeedData - Application navigation entry (once per app)
    □ ApplicationRolesSeedData - Application-scoped roles (once per app)
    □ NavigationModuleSeedData - Module navigation structure (per module)
    □ PermissionsSeedData - RBAC permissions (per module)
    □ RolesSeedData - Role-permission mappings (per module)
    □ {App}SeedDataProvider - IClientSeedDataProvider (4 methods)
    Total: 2 app-level + 3 per-module + 1 provider

  [SEEDDATA] Business Reference Data
    □ Seed {Entity1} reference data
    □ Seed {Entity2} lookup values
    □ Total: Y business seed tasks

  [APPLICATION] Services & Business Logic
    □ Create {ServiceName}Service for {UC1}
    □ Create {DtoName}Dto for API contracts
    □ Create {ValidatorName}Validator for input validation
    □ Implement query handlers
    Total: Z tasks

  [INFRASTRUCTURE] Repositories & Persistence
    □ Create {Entity1}Repository with CRUD + custom queries
    □ Create {Entity2}Repository
    □ Configure DbContext for module
    □ Setup specifications for complex queries
    □ Create IClientSeedDataProvider (client projects ONLY - injects core seeds at runtime)
    □ Create DevDataSeeder + SeedConstants (if first module)
    □ Total: A tasks

  [API] REST Endpoints & Controllers
    □ Create {ModuleNameController} GET endpoints (List, GetById)
    □ Create {ModuleNameController} POST endpoint (Create)
    □ Create {ModuleNameController} PUT endpoint (Update)
    □ Create {ModuleNameController} DELETE endpoint (Delete)
    □ Implement error handling and validation responses
    Total: B tasks

  [FRONTEND] UI Components & Pages (wireframe-driven)
    □ Create {ModuleName}Page for listing [wireframe: {module}-list]
    □ Create {ModuleName}DetailPage for viewing [wireframe: {module}-detail]
    □ Create {ModuleName}Form component for creation/edit [wireframe: {module}-create]
    □ Create custom hook use{ModuleName}
    □ Implement pagination, filtering, sorting
    □ Validate all pages match their wireframe layout
    □ ⚠️ Routes MUST be INSIDE the AppLayout wrapper
    Total: C tasks

  [I18N] Internationalization Keys
    □ Define i18n keys for {Module} UI labels
    □ Setup translations for locales: fr, en, it, de
    Total: D keys

  [TESTS] Unit & Integration Tests
    □ Unit tests for {Entity} domain logic
    □ Unit tests for {ServiceName}Service
    □ Integration tests for {ModuleNameController}
    □ Security tests for authorization & tenant isolation
    □ E2E tests for critical user flows
    Total: E unit + F integration + G security = H tests

  [QA] Quality Assurance
    □ Code review against SmartStack conventions
    □ Test coverage minimum 80%
    □ Security scan for OWASP vulnerabilities
    □ Performance testing under load
    Total: 4 QA tasks

  Module Total: X + 5 + Y + Z + A + B + C + D + H + 4 = {module_total} tasks
  Estimated Effort: {simple/medium/complex} - {1-3/3-8/8-15} days

{If multi-module:}
[CROSS-MODULE] Integration Tasks
  Status: NOT STARTED
  Dependencies: All modules COMPLETED

  □ Verify cross-module entity relationships
  □ Test cross-module API dependencies
  □ Validate permission matrix across modules
  □ E2E flow tests spanning multiple modules
  □ Cross-module data consistency checks
  □ Integration test suite for module interactions
  Total: 6 CROSS-MODULE tasks

═════════════════════════════════════════════════════════════════
SUMMARY
═════════════════════════════════════════════════════════════════
Total Modules:         {count}
Total Tasks:           {total_count}
  - CORE SeedData:     {count} × 5 = {total_core}
  - Business Tasks:    {total_biz}
  - Development:       {total_dev}
  - Tests:             {total_tests}
  - QA:                {total_qa}
  - Cross-Module:      {cross_module_count or 0}

Strategy:              {strategy}
Module Order:          {topological order with dependencies noted}

Complexity Distribution:
  Simple:   {count} modules ({estimate} days each)
  Medium:   {count} modules ({estimate} days each)
  Complex:  {count} modules ({estimate} days each)

Total Effort Estimate:  {total_days} days ({total_hours} hours)
Per Developer (2):      {total_days / 2} days
Parallel Potential:     {strategy_efficiency_percent}%

═════════════════════════════════════════════════════════════════
LEGEND
═════════════════════════════════════════════════════════════════
□ = Task not started
✓ = Task completed
⚠ = Task in progress
✗ = Task failed / blocked

COLORS:
[DOMAIN]      = Domain Model & Business Logic
[SEEDDATA-CORE] = MANDATORY core configuration (5 entries)
[SEEDDATA]    = Business reference & lookup data
[APPLICATION] = Services, DTOs, Validators
[INFRASTRUCTURE] = Repositories, DbContext, ORM
[API]         = REST controllers & endpoints
[FRONTEND]    = React pages, components, hooks
[I18N]        = Internationalization
[TESTS]       = Unit, Integration, Security, E2E
[QA]          = Code quality, coverage, security
[CROSS-MODULE] = Multi-module integration (if applicable)

═════════════════════════════════════════════════════════════════
```

## Progress Tracker Rules

- One section per module, in topological order (dependencies first)
- CORE SeedData ALWAYS 5 entries (mandatory)
- Business SeedData varies by module
- Hierarchical task structure (module → layer → tasks)
- Each task is independent, assignable checkbox
- Effort estimate per module (simple/medium/complex)
- Summary with totals across all modules
- Identified dependencies for parallel execution
- Cross-module tasks only if multi-module
