feat: reword phase to epic, update mkdocs

2025-11-05 09:28:33 +01:00
parent 65a428534c
commit ace9678f6c
64 changed files with 214 additions and 208 deletions
--- a/docs/content/stories/COMPLETE_TASK_LIST.md
+++ b/docs/content/stories/COMPLETE_TASK_LIST.md
@@ -1,46 +1,46 @@
 # Complete Task List

-This document provides a comprehensive list of all tasks across all phases. Each task has a corresponding detailed file in the phase-specific directories.
+This document provides a comprehensive list of all tasks across all epics. Each task has a corresponding detailed file in the epic-specific directories.

 ## Task Organization

-Tasks are organized by phase and section. Each task file follows the naming convention: `{section}.{subtask}-{description}.md`
+Tasks are organized by epic and section. Each task file follows the naming convention: `{section}.{subtask}-{description}.md`

-## Phase 0: Project Setup & Foundation
+## Epic 0: Project Setup & Foundation

 ### 0.1 Repository Bootstrap
- [0.1.1 - Initialize Go Module](./phase0/0.1.1-initialize-go-module.md)
- [0.1.2 - Create Directory Structure](./phase0/0.1.2-create-directory-structure.md)
- [0.1.3 - Add Gitignore](./phase0/0.1.3-add-gitignore.md)
- [0.1.4 - Create Initial README](./phase0/0.1.4-create-initial-readme.md)
+- [0.1.1 - Initialize Go Module](./epic0/0.1.1-initialize-go-module.md)
+- [0.1.2 - Create Directory Structure](./epic0/0.1.2-create-directory-structure.md)
+- [0.1.3 - Add Gitignore](./epic0/0.1.3-add-gitignore.md)
+- [0.1.4 - Create Initial README](./epic0/0.1.4-create-initial-readme.md)

 ### 0.2 Configuration System
- [0.2.1 - Install Configuration Dependencies](./phase0/0.2.1-install-config-dependencies.md)
- [0.2.2 - Create Config Interface](./phase0/0.2.2-create-config-interface.md)
- [0.2.3 - Implement Config Loader](./phase0/0.2.3-implement-config-loader.md)
- [0.2.4 - Create Configuration Files](./phase0/0.2.4-create-configuration-files.md)
+- [0.2.1 - Install Configuration Dependencies](./epic0/0.2.1-install-config-dependencies.md)
+- [0.2.2 - Create Config Interface](./epic0/0.2.2-create-config-interface.md)
+- [0.2.3 - Implement Config Loader](./epic0/0.2.3-implement-config-loader.md)
+- [0.2.4 - Create Configuration Files](./epic0/0.2.4-create-configuration-files.md)

 ### 0.3 Logging Foundation
- [0.3.1 - Install Logging Dependencies](./phase0/0.3.1-install-logging-dependencies.md)
- See [Phase 0 README](./phase0/README.md) for remaining tasks
+- [0.3.1 - Install Logging Dependencies](./epic0/0.3.1-install-logging-dependencies.md)
+- See [Epic 0 README](./epic0/README.md) for remaining tasks

 ### 0.4 Basic CI/CD Pipeline
- See [Phase 0 README](./phase0/README.md) for tasks
+- See [Epic 0 README](./epic0/README.md) for tasks

 ### 0.5 Dependency Injection Setup
- See [Phase 0 README](./phase0/README.md) for tasks
+- See [Epic 0 README](./epic0/README.md) for tasks

-## Phase 1-8 Tasks
+## Epic 1-8 Tasks

-Detailed task files for Phases 1-8 are being created. See individual phase README files:
- [Phase 1 README](./phase1/README.md) - Core Kernel & Infrastructure
- [Phase 2 README](./phase2/README.md) - Authentication & Authorization
- [Phase 3 README](./phase3/README.md) - Module Framework
- [Phase 4 README](./phase4/README.md) - Sample Feature Module (Blog)
- [Phase 5 README](./phase5/README.md) - Infrastructure Adapters
- [Phase 6 README](./phase6/README.md) - Observability & Production Readiness
- [Phase 7 README](./phase7/README.md) - Testing, Documentation & CI/CD
- [Phase 8 README](./phase8/README.md) - Advanced Features & Polish
+Detailed task files for Epics 1-8 are being created. See individual epic README files:
+- [Epic 1 README](./epic1/README.md) - Core Kernel & Infrastructure
+- [Epic 2 README](./epic2/README.md) - Authentication & Authorization
+- [Epic 3 README](./epic3/README.md) - Module Framework
+- [Epic 4 README](./epic4/README.md) - Sample Feature Module (Blog)
+- [Epic 5 README](./epic5/README.md) - Infrastructure Adapters
+- [Epic 6 README](./epic6/README.md) - Observability & Production Readiness
+- [Epic 7 README](./epic7/README.md) - Testing, Documentation & CI/CD
+- [Epic 8 README](./epic8/README.md) - Advanced Features & Polish

 ## Task Status Tracking

--- a/docs/content/stories/README.md
+++ b/docs/content/stories/README.md
@@ -1,44 +1,44 @@
 # Implementation Tasks

-This directory contains detailed task definitions for each phase of the Go Platform implementation.
+This directory contains detailed task definitions for each epic of the Go Platform implementation.

 ## Task Organization

-Tasks are organized by phase, with each major task section having its own detailed file:
+Tasks are organized by epic, with each major task section having its own detailed file:

-### Phase 0: Project Setup & Foundation
- [Phase 0 Tasks](./phase0/README.md) - All Phase 0 tasks
+### Epic 0: Project Setup & Foundation
+- [Epic 0 Tasks](./epic0/README.md) - All Epic 0 tasks

-### Phase 1: Core Kernel & Infrastructure
- [Phase 1 Tasks](./phase1/README.md) - All Phase 1 tasks
+### Epic 1: Core Kernel & Infrastructure
+- [Epic 1 Tasks](./epic1/README.md) - All Epic 1 tasks

-### Phase 2: Authentication & Authorization
- [Phase 2 Tasks](./phase2/README.md) - All Phase 2 tasks
+### Epic 2: Authentication & Authorization
+- [Epic 2 Tasks](./epic2/README.md) - All Epic 2 tasks

-### Phase 3: Module Framework
- [Phase 3 Tasks](./phase3/README.md) - All Phase 3 tasks
+### Epic 3: Module Framework
+- [Epic 3 Tasks](./epic3/README.md) - All Epic 3 tasks

-### Phase 4: Sample Feature Module (Blog)
- [Phase 4 Tasks](./phase4/README.md) - All Phase 4 tasks
+### Epic 4: Sample Feature Module (Blog)
+- [Epic 4 Tasks](./epic4/README.md) - All Epic 4 tasks

-### Phase 5: Infrastructure Adapters
- [Phase 5 Tasks](./phase5/README.md) - All Phase 5 tasks
+### Epic 5: Infrastructure Adapters
+- [Epic 5 Tasks](./epic5/README.md) - All Epic 5 tasks

-### Phase 6: Observability & Production Readiness
- [Phase 6 Tasks](./phase6/README.md) - All Phase 6 tasks
+### Epic 6: Observability & Production Readiness
+- [Epic 6 Tasks](./epic6/README.md) - All Epic 6 tasks

-### Phase 7: Testing, Documentation & CI/CD
- [Phase 7 Tasks](./phase7/README.md) - All Phase 7 tasks
+### Epic 7: Testing, Documentation & CI/CD
+- [Epic 7 Tasks](./epic7/README.md) - All Epic 7 tasks

-### Phase 8: Advanced Features & Polish (Optional)
- [Phase 8 Tasks](./phase8/README.md) - All Phase 8 tasks
+### Epic 8: Advanced Features & Polish (Optional)
+- [Epic 8 Tasks](./epic8/README.md) - All Epic 8 tasks

 ## Task Status

 Each task file includes:
 - **Task ID**: Unique identifier (e.g., `0.1.1`)
 - **Title**: Descriptive task name
- **Phase**: Implementation phase
+- **Epic**: Implementation epic
 - **Status**: Pending | In Progress | Completed | Blocked
 - **Priority**: High | Medium | Low
 - **Dependencies**: Tasks that must complete first
@@ -57,7 +57,7 @@ Tasks can be tracked using:

 ## Task Naming Convention

-Tasks follow the format: `{phase}.{section}.{subtask}`
+Tasks follow the format: `{epic}.{section}.{subtask}`

-Example: `0.1.1` = Phase 0, Section 1 (Repository Bootstrap), Subtask 1
+Example: `0.1.1` = Epic 0, Section 1 (Repository Bootstrap), Subtask 1

--- a/docs/content/stories/STORY_CONSOLIDATION_GUIDE.md
+++ b/docs/content/stories/STORY_CONSOLIDATION_GUIDE.md
@@ -26,7 +26,7 @@ Each consolidated story follows this structure:
 4. **Acceptance Criteria** - How we know it's done
 5. **Implementation Steps** - High-level steps (not micro-tasks)

-## Phase 0 - Completed Examples
+## Epic 0 - Completed Examples

 ### 0.1 Project Initialization and Repository Structure
 **Consolidates:** Go module init, directory structure, .gitignore, README
@@ -43,17 +43,18 @@ Each consolidated story follows this structure:
 ### 0.5 DI and Application Bootstrap
 **Consolidates:** Install FX, create DI container, create main.go

-## Remaining Phases - Consolidation Pattern
+## Remaining Epics - Consolidation Pattern

-### Phase 1: Core Kernel
+### Epic 1: Core Kernel
 - **1.1 Enhanced DI Container** - All DI providers and extensions
 - **1.2 Database Layer** - Complete Ent setup with entities and migrations
 - **1.3 Health & Metrics** - Complete monitoring system
 - **1.4 Error Handling** - Complete error bus system
 - **1.5 HTTP Server** - Complete server with all middleware
 - **1.6 OpenTelemetry** - Complete tracing setup
+- **1.7 Service Client Interfaces** - Complete service abstraction layer

-### Phase 2: Authentication & Authorization
+### Epic 2: Authentication & Authorization
 - **2.1 JWT Authentication System** - Complete auth with tokens
 - **2.2 Identity Management** - Complete user lifecycle
 - **2.3 RBAC System** - Complete permission system
@@ -61,25 +62,26 @@ Each consolidated story follows this structure:
 - **2.5 Audit Logging** - Complete audit system
 - **2.6 Database Seeding** - Complete seeding system

-### Phase 3: Module Framework
+### Epic 3: Module Framework
 - **3.1 Module Interface & Registry** - Complete module system
 - **3.2 Permission Code Generation** - Complete code gen system
 - **3.3 Module Loader** - Complete loading and initialization
 - **3.4 Module CLI** - Complete CLI tool
+- **3.5 Service Registry** - Complete service discovery

-### Phase 4: Sample Blog Module
+### Epic 4: Sample Blog Module
 - **4.1 Complete Blog Module** - Full module with CRUD, permissions, API

-### Phase 5: Infrastructure Adapters
+### Epic 5: Infrastructure Adapters
 - **5.1 Cache System** - Complete Redis cache
 - **5.2 Event Bus** - Complete event system
 - **5.3 Blob Storage** - Complete S3 storage
 - **5.4 Email Notification** - Complete email system
 - **5.5 Scheduler & Jobs** - Complete job system
 - **5.6 Secret Store** - Complete secret management
- **5.7 Multi-tenancy** - Complete tenant support
+- **5.7 gRPC Services** - Complete gRPC service definitions and clients

-### Phase 6: Observability
+### Epic 6: Observability
 - **6.1 Enhanced OpenTelemetry** - Complete tracing
 - **6.2 Error Reporting** - Complete Sentry integration
 - **6.3 Enhanced Logging** - Complete log correlation
@@ -89,14 +91,14 @@ Each consolidated story follows this structure:
 - **6.7 Security Hardening** - Complete security
 - **6.8 Performance Optimization** - Complete optimizations

-### Phase 7: Testing & Documentation
+### Epic 7: Testing & Documentation
 - **7.1 Unit Testing** - Complete test suite
 - **7.2 Integration Testing** - Complete integration tests
 - **7.3 Documentation** - Complete docs
 - **7.4 CI/CD Enhancement** - Complete pipeline
 - **7.5 Docker & Deployment** - Complete deployment setup

-### Phase 8: Advanced Features
+### Epic 8: Advanced Features
 - **8.1 OIDC Support** - Complete OIDC
 - **8.2 GraphQL API** - Complete GraphQL
 - **8.3 Additional Modules** - Complete sample modules
@@ -104,7 +106,7 @@ Each consolidated story follows this structure:

 ## Creating New Story Files

-When creating story files for remaining phases, follow this template:
+When creating story files for remaining epics, follow this template:

 ```markdown
 # Story X.Y: [Meaningful Title]
@@ -112,7 +114,7 @@ When creating story files for remaining phases, follow this template:
 ## Metadata
 - **Story ID**: X.Y
 - **Title**: [Complete Feature Name]
- **Phase**: X - [Phase Name]
+- **Epic**: X - [Epic Name]
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: [hours]
@@ -164,9 +166,9 @@ When creating story files for remaining phases, follow this template:

 ## Next Steps

-1. Update remaining phase README files to reference consolidated stories
-2. Create story files for remaining phases following the pattern
-3. Update plan.md to complete all phases with story-based structure
+1. Update remaining epic README files to reference consolidated stories
+2. Create story files for remaining epics following the pattern
+3. Update plan.md to complete all epics with story-based structure
 4. Remove old granular task files (or archive them)

 ## Benefits of This Approach
--- a/docs/content/stories/phase0/0.1-project-initialization.md
+++ b/docs/content/stories/phase0/0.1-project-initialization.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 0.1
 - **Title**: Project Initialization and Repository Structure
- **Phase**: 0 - Project Setup & Foundation
+- **Epic**: 0 - Project Setup & Foundation
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 2-3 hours
@@ -44,7 +44,7 @@ platform/
 │   ├── perm/              # Permission DSL
 │   └── infra/             # Infrastructure interfaces
 ├── modules/               # Feature modules
-│   └── blog/              # Sample Blog module (Phase 4)
+│   └── blog/              # Sample Blog module (Epic 4)
 ├── config/                # Configuration files
 │   ├── default.yaml
 │   ├── development.yaml
--- a/docs/content/stories/phase0/0.2-configuration-management-system.md
+++ b/docs/content/stories/phase0/0.2-configuration-management-system.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 0.2
 - **Title**: Configuration Management System
- **Phase**: 0 - Project Setup & Foundation
+- **Epic**: 0 - Project Setup & Foundation
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 4-6 hours
@@ -145,7 +145,7 @@ logging:
 - Consider adding configuration schema validation in future
 - Environment variable format: `SERVER_PORT`, `DATABASE_DSN`, etc.
 - Configuration files should be in YAML for readability
- Support secret manager integration placeholder (Phase 6)
+- Support secret manager integration placeholder (Epic 6)

 ## Testing
 ```bash
--- a/docs/content/stories/phase0/0.3-structured-logging-system.md
+++ b/docs/content/stories/phase0/0.3-structured-logging-system.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 0.3
 - **Title**: Structured Logging System
- **Phase**: 0 - Project Setup & Foundation
+- **Epic**: 0 - Project Setup & Foundation
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 4-6 hours
--- a/docs/content/stories/phase0/0.4-cicd-pipeline.md
+++ b/docs/content/stories/phase0/0.4-cicd-pipeline.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 0.4
 - **Title**: CI/CD Pipeline and Development Tooling
- **Phase**: 0 - Project Setup & Foundation
+- **Epic**: 0 - Project Setup & Foundation
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 3-4 hours
--- a/docs/content/stories/phase0/0.5-di-and-bootstrap.md
+++ b/docs/content/stories/phase0/0.5-di-and-bootstrap.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 0.5
 - **Title**: Dependency Injection and Application Bootstrap
- **Phase**: 0 - Project Setup & Foundation
+- **Epic**: 0 - Project Setup & Foundation
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 4-5 hours
@@ -36,7 +36,7 @@ Main application bootstrap:
 - Load configuration
 - Initialize DI container with core services
 - Set up basic application lifecycle
- Start minimal HTTP server (placeholder for Phase 1)
+- Start minimal HTTP server (placeholder for Epic 1)
 - Handle graceful shutdown (SIGINT, SIGTERM)
 - Proper error handling and logging

--- a/docs/content/stories/phase0/README.md
+++ b/docs/content/stories/phase0/README.md
@@ -1,4 +1,4 @@
-# Phase 0: Project Setup & Foundation
+# Epic 0: Project Setup & Foundation

 ## Overview
 Initialize repository structure with proper Go project layout, implement configuration management system, establish structured logging system, set up CI/CD pipeline and development tooling, and bootstrap dependency injection and application entry point.
--- a/docs/content/stories/phase1/1.1-enhanced-di-container.md
+++ b/docs/content/stories/phase1/1.1-enhanced-di-container.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 1.1
 - **Title**: Enhanced Dependency Injection Container
- **Phase**: 1 - Core Kernel & Infrastructure
+- **Epic**: 1 - Core Kernel & Infrastructure
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 3-4 hours
--- a/docs/content/stories/phase1/1.2-database-layer.md
+++ b/docs/content/stories/phase1/1.2-database-layer.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 1.2
 - **Title**: Database Layer with Ent ORM
- **Phase**: 1 - Core Kernel & Infrastructure
+- **Epic**: 1 - Core Kernel & Infrastructure
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 6-8 hours
@@ -116,7 +116,7 @@ Define core entities:
 - Run migrations on application startup
 - Add proper indexes for performance
 - Handle database connection errors gracefully
- Support for database migrations in future phases
+- Support for database migrations in future epics

 ## Testing
 ```bash
--- a/docs/content/stories/phase1/1.3-health-metrics-system.md
+++ b/docs/content/stories/phase1/1.3-health-metrics-system.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 1.3
 - **Title**: Health Monitoring and Metrics System
- **Phase**: 1 - Core Kernel & Infrastructure
+- **Epic**: 1 - Core Kernel & Infrastructure
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 5-6 hours
--- a/docs/content/stories/phase1/1.4-error-handling.md
+++ b/docs/content/stories/phase1/1.4-error-handling.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 1.4
 - **Title**: Error Handling and Error Bus
- **Phase**: 1 - Core Kernel & Infrastructure
+- **Epic**: 1 - Core Kernel & Infrastructure
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 4-5 hours
@@ -27,7 +27,7 @@ This story creates a complete error handling system with an error bus that captu
 - Background goroutine consumes errors
 - Logs all errors with context (request ID, user ID, etc.)
 - Error aggregation
- Optional: Sentry integration placeholder (Phase 6)
+- Optional: Sentry integration placeholder (Epic 6)

 ### 3. Panic Recovery Middleware
 - Recovers from panics in HTTP handlers
@@ -84,7 +84,7 @@ This story creates a complete error handling system with an error bus that captu
 - Background goroutine should handle errors asynchronously
 - Preserve error context (stack traces, request IDs)
 - Consider error rate limiting in future
- Placeholder for Sentry integration in Phase 6
+- Placeholder for Sentry integration in Epic 6

 ## Testing
 ```bash
--- a/docs/content/stories/phase1/1.5-http-server.md
+++ b/docs/content/stories/phase1/1.5-http-server.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 1.5
 - **Title**: HTTP Server Foundation with Middleware Stack
- **Phase**: 1 - Core Kernel & Infrastructure
+- **Epic**: 1 - Core Kernel & Infrastructure
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 6-8 hours
@@ -98,7 +98,7 @@ This story implements a complete HTTP server using Gin with a comprehensive midd
 - Middleware order is important
 - Support graceful shutdown with connection draining
 - CORS should be configurable per environment
- Consider adding rate limiting in future (Phase 6)
+- Consider adding rate limiting in future (Epic 6)

 ## Testing
 ```bash
--- a/docs/content/stories/phase1/1.6-opentelemetry.md
+++ b/docs/content/stories/phase1/1.6-opentelemetry.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 1.6
 - **Title**: OpenTelemetry Distributed Tracing
- **Phase**: 1 - Core Kernel & Infrastructure
+- **Epic**: 1 - Core Kernel & Infrastructure
 - **Status**: Pending
 - **Priority**: Medium
 - **Estimated Time**: 5-6 hours
--- a/docs/content/stories/phase1/1.7-service-abstraction-layer.md
+++ b/docs/content/stories/phase1/1.7-service-abstraction-layer.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 1.7
 - **Title**: Service Client Interfaces
- **Phase**: 1 - Core Kernel & Infrastructure
+- **Epic**: 1 - Core Kernel & Infrastructure
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 4-6 hours
@@ -93,7 +93,7 @@ Factory pattern for creating service clients:
 - Use context for all operations
 - Support cancellation and timeouts
 - Design for network calls (retries, circuit breakers)
- gRPC will be implemented in Phase 5, but interfaces are defined here
+- gRPC will be implemented in Epic 5, but interfaces are defined here

 ## Testing
 ```bash
--- a/docs/content/stories/phase1/README.md
+++ b/docs/content/stories/phase1/README.md
@@ -1,4 +1,4 @@
-# Phase 1: Core Kernel & Infrastructure
+# Epic 1: Core Kernel & Infrastructure

 ## Overview
 Extend DI container to support all core services, implement database layer with Ent ORM, build health monitoring and metrics system, create error handling and error bus, establish HTTP server with comprehensive middleware stack, and integrate OpenTelemetry for distributed tracing.
--- a/docs/content/stories/phase2/2.1-jwt-authentication.md
+++ b/docs/content/stories/phase2/2.1-jwt-authentication.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 2.1
 - **Title**: JWT Authentication System
- **Phase**: 2 - Authentication & Authorization
+- **Epic**: 2 - Authentication & Authorization
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 6-8 hours
--- a/docs/content/stories/phase2/2.2-identity-management.md
+++ b/docs/content/stories/phase2/2.2-identity-management.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 2.2
 - **Title**: Identity Management System
- **Phase**: 2 - Authentication & Authorization
+- **Epic**: 2 - Authentication & Authorization
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 8-10 hours
@@ -53,7 +53,7 @@ This story implements the complete user identity management system including use
 - Service registration in service registry

 ### 6. Integration
- Integration with email notification system (Phase 5 placeholder)
+- Integration with email notification system (Epic 5 placeholder)
 - Integration with audit logging
 - Integration with authentication system
 - Identity service is an independent service that can be deployed separately
--- a/docs/content/stories/phase2/2.3-rbac-system.md
+++ b/docs/content/stories/phase2/2.3-rbac-system.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 2.3
 - **Title**: Role-Based Access Control (RBAC) System
- **Phase**: 2 - Authentication & Authorization
+- **Epic**: 2 - Authentication & Authorization
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 6-8 hours
--- a/docs/content/stories/phase2/2.4-role-management.md
+++ b/docs/content/stories/phase2/2.4-role-management.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 2.4
 - **Title**: Role Management API
- **Phase**: 2 - Authentication & Authorization
+- **Epic**: 2 - Authentication & Authorization
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 5-6 hours
--- a/docs/content/stories/phase2/2.5-audit-logging.md
+++ b/docs/content/stories/phase2/2.5-audit-logging.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 2.5
 - **Title**: Audit Logging System
- **Phase**: 2 - Authentication & Authorization
+- **Epic**: 2 - Authentication & Authorization
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 5-6 hours
--- a/docs/content/stories/phase2/2.6-database-seeding.md
+++ b/docs/content/stories/phase2/2.6-database-seeding.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 2.6
 - **Title**: Database Seeding and Initialization
- **Phase**: 2 - Authentication & Authorization
+- **Epic**: 2 - Authentication & Authorization
 - **Status**: Pending
 - **Priority**: Medium
 - **Estimated Time**: 3-4 hours
--- a/docs/content/stories/phase2/README.md
+++ b/docs/content/stories/phase2/README.md
@@ -1,4 +1,4 @@
-# Phase 2: Authentication & Authorization
+# Epic 2: Authentication & Authorization

 ## Overview
 Implement complete JWT-based authentication system, build comprehensive identity management with user lifecycle, create role-based access control (RBAC) system, implement authorization middleware and permission checks, add comprehensive audit logging for security compliance, and provide database seeding for initial setup. All core services (Auth, Identity, Authz, Audit) are independent microservices that expose gRPC servers and register with the service registry.
--- a/docs/content/stories/phase3/3.1-module-system-interface.md
+++ b/docs/content/stories/phase3/3.1-module-system-interface.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 3.1
 - **Title**: Module System Interface and Registry
- **Phase**: 3 - Module Framework
+- **Epic**: 3 - Module Framework
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 5-6 hours
--- a/docs/content/stories/phase3/3.2-permission-code-generation.md
+++ b/docs/content/stories/phase3/3.2-permission-code-generation.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 3.2
 - **Title**: Permission Code Generation System
- **Phase**: 3 - Module Framework
+- **Epic**: 3 - Module Framework
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 4-5 hours
--- a/docs/content/stories/phase3/3.3-module-loader.md
+++ b/docs/content/stories/phase3/3.3-module-loader.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 3.3
 - **Title**: Module Loader and Initialization
- **Phase**: 3 - Module Framework
+- **Epic**: 3 - Module Framework
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 6-8 hours
--- a/docs/content/stories/phase3/3.4-module-cli.md
+++ b/docs/content/stories/phase3/3.4-module-cli.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 3.4
 - **Title**: Module Management CLI Tool
- **Phase**: 3 - Module Framework
+- **Epic**: 3 - Module Framework
 - **Status**: Pending
 - **Priority**: Medium
 - **Estimated Time**: 4-5 hours
--- a/docs/content/stories/phase3/3.5-service-registry.md
+++ b/docs/content/stories/phase3/3.5-service-registry.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 3.5
 - **Title**: Service Registry and Discovery
- **Phase**: 3 - Module Framework
+- **Epic**: 3 - Module Framework
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 5-6 hours
--- a/docs/content/stories/phase3/README.md
+++ b/docs/content/stories/phase3/README.md
@@ -1,4 +1,4 @@
-# Phase 3: Module Framework
+# Epic 3: Module Framework

 ## Overview
 Design and implement complete module system interface, build module registry with dependency resolution, create permission code generation from module manifests, implement module loader supporting static and dynamic loading, add module lifecycle management and initialization, and provide CLI tooling for module management.
--- a/docs/content/stories/phase4/4.1-blog-module.md
+++ b/docs/content/stories/phase4/4.1-blog-module.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 4.1
 - **Title**: Complete Blog Module
- **Phase**: 4 - Sample Feature Module (Blog)
+- **Epic**: 4 - Sample Feature Module (Blog)
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 10-12 hours
--- a/docs/content/stories/phase4/README.md
+++ b/docs/content/stories/phase4/README.md
@@ -1,4 +1,4 @@
-# Phase 4: Sample Feature Module (Blog)
+# Epic 4: Sample Feature Module (Blog)

 ## Overview
 Create a complete sample module (Blog) to demonstrate the framework, showing how to add routes, permissions, database entities, and services. The Blog module is an independent service that uses service clients to communicate with core services. Provide reference implementation for future developers.
--- a/docs/content/stories/phase5/5.1-cache-system.md
+++ b/docs/content/stories/phase5/5.1-cache-system.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 5.1
 - **Title**: Cache System (Redis)
- **Phase**: 5 - Infrastructure Adapters
+- **Epic**: 5 - Infrastructure Adapters
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 4-5 hours
--- a/docs/content/stories/phase5/5.2-event-bus.md
+++ b/docs/content/stories/phase5/5.2-event-bus.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 5.2
 - **Title**: Event Bus System
- **Phase**: 5 - Infrastructure Adapters
+- **Epic**: 5 - Infrastructure Adapters
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 6-8 hours
--- a/docs/content/stories/phase5/5.3-blob-storage.md
+++ b/docs/content/stories/phase5/5.3-blob-storage.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 5.3
 - **Title**: Blob Storage System
- **Phase**: 5 - Infrastructure Adapters
+- **Epic**: 5 - Infrastructure Adapters
 - **Status**: Pending
 - **Priority**: Medium
 - **Estimated Time**: 5-6 hours
--- a/docs/content/stories/phase5/5.4-email-notification.md
+++ b/docs/content/stories/phase5/5.4-email-notification.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 5.4
 - **Title**: Email Notification System
- **Phase**: 5 - Infrastructure Adapters
+- **Epic**: 5 - Infrastructure Adapters
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 5-6 hours
--- a/docs/content/stories/phase5/5.5-scheduler-jobs.md
+++ b/docs/content/stories/phase5/5.5-scheduler-jobs.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 5.5
 - **Title**: Scheduler and Background Jobs System
- **Phase**: 5 - Infrastructure Adapters
+- **Epic**: 5 - Infrastructure Adapters
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 6-8 hours
--- a/docs/content/stories/phase5/5.6-secret-store.md
+++ b/docs/content/stories/phase5/5.6-secret-store.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 5.6
 - **Title**: Secret Store Integration
- **Phase**: 5 - Infrastructure Adapters
+- **Epic**: 5 - Infrastructure Adapters
 - **Status**: Pending
 - **Priority**: Medium
 - **Estimated Time**: 4-5 hours
--- a/docs/content/stories/phase5/5.7-grpc-services.md
+++ b/docs/content/stories/phase5/5.7-grpc-services.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 5.7
 - **Title**: gRPC Service Definitions and Clients
- **Phase**: 5 - Infrastructure Adapters
+- **Epic**: 5 - Infrastructure Adapters
 - **Status**: Pending
 - **Priority**: Medium
 - **Estimated Time**: 8-10 hours
--- a/docs/content/stories/phase5/README.md
+++ b/docs/content/stories/phase5/README.md
@@ -1,4 +1,4 @@
-# Phase 5: Infrastructure Adapters
+# Epic 5: Infrastructure Adapters

 ## Overview
 Implement infrastructure adapters (cache, queue, blob storage, email), make adapters swappable via interfaces, add scheduler/background jobs system, and implement event bus (in-process and Kafka).
--- a/docs/content/stories/phase6/6.1-enhanced-observability.md
+++ b/docs/content/stories/phase6/6.1-enhanced-observability.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 6.1
 - **Title**: Enhanced Observability
- **Phase**: 6 - Observability & Production Readiness
+- **Epic**: 6 - Observability & Production Readiness
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 6-8 hours
--- a/docs/content/stories/phase6/6.2-error-reporting.md
+++ b/docs/content/stories/phase6/6.2-error-reporting.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 6.2
 - **Title**: Error Reporting (Sentry)
- **Phase**: 6 - Observability & Production Readiness
+- **Epic**: 6 - Observability & Production Readiness
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 4-5 hours
--- a/docs/content/stories/phase6/6.3-grafana-dashboards.md
+++ b/docs/content/stories/phase6/6.3-grafana-dashboards.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 6.3
 - **Title**: Grafana Dashboards
- **Phase**: 6 - Observability & Production Readiness
+- **Epic**: 6 - Observability & Production Readiness
 - **Status**: Pending
 - **Priority**: Medium
 - **Estimated Time**: 4-5 hours
--- a/docs/content/stories/phase6/6.4-rate-limiting.md
+++ b/docs/content/stories/phase6/6.4-rate-limiting.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 6.4
 - **Title**: Rate Limiting
- **Phase**: 6 - Observability & Production Readiness
+- **Epic**: 6 - Observability & Production Readiness
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 4-5 hours
--- a/docs/content/stories/phase6/6.5-security-hardening.md
+++ b/docs/content/stories/phase6/6.5-security-hardening.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 6.5
 - **Title**: Security Hardening
- **Phase**: 6 - Observability & Production Readiness
+- **Epic**: 6 - Observability & Production Readiness
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 5-6 hours
--- a/docs/content/stories/phase6/6.6-performance-optimization.md
+++ b/docs/content/stories/phase6/6.6-performance-optimization.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 6.6
 - **Title**: Performance Optimization
- **Phase**: 6 - Observability & Production Readiness
+- **Epic**: 6 - Observability & Production Readiness
 - **Status**: Pending
 - **Priority**: Medium
 - **Estimated Time**: 6-8 hours
--- a/docs/content/stories/phase6/README.md
+++ b/docs/content/stories/phase6/README.md
@@ -1,4 +1,4 @@
-# Phase 6: Observability & Production Readiness
+# Epic 6: Observability & Production Readiness

 ## Overview
 Enhance observability with full OpenTelemetry integration, add comprehensive error reporting (Sentry), create Grafana dashboards, improve logging with request correlation, add rate limiting and security hardening, and optimize performance.
--- a/docs/content/stories/phase7/7.1-testing-suite.md
+++ b/docs/content/stories/phase7/7.1-testing-suite.md
@@ -3,11 +3,11 @@
 ## Metadata
 - **Story ID**: 7.1
 - **Title**: Comprehensive Testing Suite
- **Phase**: 7 - Testing, Documentation & CI/CD
+- **Epic**: 7 - Testing, Documentation & CI/CD
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 10-12 hours
- **Dependencies**: All previous phases
+- **Dependencies**: All previous epics

 ## Goal
 Achieve comprehensive test coverage with unit tests, integration tests, and contract tests.
--- a/docs/content/stories/phase7/7.2-documentation.md
+++ b/docs/content/stories/phase7/7.2-documentation.md
@@ -3,11 +3,11 @@
 ## Metadata
 - **Story ID**: 7.2
 - **Title**: Complete Documentation
- **Phase**: 7 - Testing, Documentation & CI/CD
+- **Epic**: 7 - Testing, Documentation & CI/CD
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 8-10 hours
- **Dependencies**: All previous phases
+- **Dependencies**: All previous epics

 ## Goal
 Create comprehensive documentation covering architecture, API, operations, and developer guides.
--- a/docs/content/stories/phase7/7.3-cicd-enhancement.md
+++ b/docs/content/stories/phase7/7.3-cicd-enhancement.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 7.3
 - **Title**: CI/CD Pipeline Enhancement
- **Phase**: 7 - Testing, Documentation & CI/CD
+- **Epic**: 7 - Testing, Documentation & CI/CD
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 5-6 hours
--- a/docs/content/stories/phase7/7.4-docker-deployment.md
+++ b/docs/content/stories/phase7/7.4-docker-deployment.md
@@ -3,11 +3,11 @@
 ## Metadata
 - **Story ID**: 7.4
 - **Title**: Docker and Deployment
- **Phase**: 7 - Testing, Documentation & CI/CD
+- **Epic**: 7 - Testing, Documentation & CI/CD
 - **Status**: Pending
 - **Priority**: High
 - **Estimated Time**: 6-8 hours
- **Dependencies**: All previous phases
+- **Dependencies**: All previous epics

 ## Goal
 Create production-ready Docker images and comprehensive deployment guides.
--- a/docs/content/stories/phase7/README.md
+++ b/docs/content/stories/phase7/README.md
@@ -1,4 +1,4 @@
-# Phase 7: Testing, Documentation & CI/CD
+# Epic 7: Testing, Documentation & CI/CD

 ## Overview
 Comprehensive test coverage (unit, integration, contract), complete documentation, production-ready CI/CD pipeline, Docker images and deployment guides, and developer tooling.
--- a/docs/content/stories/phase8/8.1-oidc-support.md
+++ b/docs/content/stories/phase8/8.1-oidc-support.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 8.1
 - **Title**: OpenID Connect (OIDC) Support
- **Phase**: 8 - Advanced Features & Polish
+- **Epic**: 8 - Advanced Features & Polish
 - **Status**: Pending
 - **Priority**: Low
 - **Estimated Time**: 6-8 hours
--- a/docs/content/stories/phase8/8.2-graphql-api.md
+++ b/docs/content/stories/phase8/8.2-graphql-api.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 8.2
 - **Title**: GraphQL API
- **Phase**: 8 - Advanced Features & Polish
+- **Epic**: 8 - Advanced Features & Polish
 - **Status**: Pending
 - **Priority**: Low
 - **Estimated Time**: 8-10 hours
--- a/docs/content/stories/phase8/8.3-additional-modules.md
+++ b/docs/content/stories/phase8/8.3-additional-modules.md
@@ -3,7 +3,7 @@
 ## Metadata
 - **Story ID**: 8.3
 - **Title**: Additional Sample Modules
- **Phase**: 8 - Advanced Features & Polish
+- **Epic**: 8 - Advanced Features & Polish
 - **Status**: Pending
 - **Priority**: Low
 - **Estimated Time**: 10-12 hours
--- a/docs/content/stories/phase8/8.4-final-polish.md
+++ b/docs/content/stories/phase8/8.4-final-polish.md
@@ -3,11 +3,11 @@
 ## Metadata
 - **Story ID**: 8.4
 - **Title**: Final Polish and Optimization
- **Phase**: 8 - Advanced Features & Polish
+- **Epic**: 8 - Advanced Features & Polish
 - **Status**: Pending
 - **Priority**: Medium
 - **Estimated Time**: 8-10 hours
- **Dependencies**: All previous phases
+- **Dependencies**: All previous epics

 ## Goal
 Final polish, bug fixes, performance optimization, and security audit.
--- a/docs/content/stories/phase8/README.md
+++ b/docs/content/stories/phase8/README.md
@@ -1,4 +1,4 @@
-# Phase 8: Advanced Features & Polish
+# Epic 8: Advanced Features & Polish

 ## Overview
 Add advanced features (OIDC, GraphQL, API Gateway), performance optimization, additional sample modules, and final polish and bug fixes.