# BR-COMMON-001: Phase Value Format Standard

**Category**: COMMON
**Priority**: P0 (CRITICAL)
**Status**: ✅ **APPROVED** - 2025-12-11
**Authority**: 🏛️ **AUTHORITATIVE** - Governing Standard for All Services
**Affects**: All CRD Controllers

---

## 🏛️ **AUTHORITATIVE STANDARD**

This document is the **single source of truth** for phase value formatting across all Kubernaut services. All service teams MUST follow this standard. Any conflicting documentation or implementation is superseded by this requirement.

**Governance**:
- All new CRDs MUST comply before merge
- Existing CRDs MUST migrate to compliance
- Cross-service integration MUST reference this standard
- All phase-related decisions defer to this document

---

## 📋 **Business Requirement**

### **Summary**
All Kubernaut CRD phase/status fields MUST use capitalized values to align with Kubernetes API conventions and ensure cross-service consistency.

### **Business Value**
- **Consistency**: Uniform phase format across all 7 CRD controllers
- **User Familiarity**: Operators expect capitalized phases from Kubernetes experience
- **Tooling Compatibility**: Many K8s tools assume capitalized phase values
- **Integration Safety**: Prevents bugs when services depend on each other's phases

---

## 🎯 **Standard Phase Values**

### **Mandatory Capitalization**

| Phase Category | Correct ✅ | Incorrect ❌ | Usage |
|----------------|-----------|--------------|-------|
| **Initial** | `"Pending"` | `"pending"` | Waiting to start |
| **Active Processing** | `"Enriching"`, `"Analyzing"`, `"Executing"` | lowercase variants | In progress |
| **Terminal Success** | `"Completed"`, `"Succeeded"` | `"completed"`, `"succeeded"` | Successfully finished |
| **Terminal Failure** | `"Failed"` | `"failed"` | Error state |
| **Skipped** | `"Skipped"` | `"skipped"` | Execution not needed |

### **Custom Phase Naming**
For service-specific phases, use **PascalCase**:
- ✅ `"AwaitingApproval"`
- ✅ `"ManualReview"`
- ✅ `"TimedOut"`
- ✅ `"WaitingForPropagation"` (EffectivenessAssessment, Issue #253)
- ❌ `"awaiting-approval"`, `"manual_review"`, `"timedout"`

---

## 📊 **Service Compliance Matrix**

| Service | Phase Field | Compliant | Fixed Date |
|---------|-------------|-----------|------------|
| **SignalProcessing** | `status.phase` | ✅ | 2025-12-11 |
| **AIAnalysis** | `status.phase` | ✅ | Pre-existing |
| **WorkflowExecution** | `status.phase` | ✅ | Pre-existing |
| **Notification** | `status.phase` | ✅ | Pre-existing |
| **RemediationRequest** | `status.overallPhase` | ✅ | Pre-existing |
| **RemediationOrchestrator** | N/A | N/A | No phase field |
| **Gateway** | N/A | N/A | Stateless service |

**DataStorage**: Audit events use lowercase action strings (e.g., `"completed"`, `"failed"`) - this is intentional for audit event schemas and does NOT violate this BR.

---

## 🔧 **Implementation Requirements**

### **1. CRD Type Definition**

```go
// api/{service}/v1alpha1/{service}_types.go

// Phase type with kubebuilder validation
// BR-COMMON-001: Capitalized phase values per Kubernetes API conventions
// +kubebuilder:validation:Enum=Pending;Processing;Completed;Failed
type ServicePhase string

const (
    PhasePending   ServicePhase = "Pending"    // ✅ Capitalized
    PhaseProcessing ServicePhase = "Processing" // ✅ Capitalized
    PhaseCompleted  ServicePhase = "Completed"  // ✅ Capitalized
    PhaseFailed     ServicePhase = "Failed"     // ✅ Capitalized
)
```

### **2. Controller Logic**

```go
// Use constants, not hardcoded strings
sp.Status.Phase = signalprocessingv1.PhaseCompleted // ✅ CORRECT

// ❌ FORBIDDEN: Hardcoded lowercase strings
sp.Status.Phase = "completed" // ❌ WRONG
```

### **3. Test Code**

```go
// Use constants or string() conversion
Expect(sp.Status.Phase).To(Equal(signalprocessingv1.PhaseCompleted)) // ✅ CORRECT

// If string comparison required, use string() conversion
auditClient.RecordPhaseTransition(ctx, sp,
    string(signalprocessingv1.PhasePending),    // ✅ CORRECT
    string(signalprocessingv1.PhaseEnriching))  // ✅ CORRECT
```

---

## 📚 **Kubernetes API Convention Reference**

**Source**: [Kubernetes API Conventions - Status Fields](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status)

**Key Guidelines**:
> Phase values should be capitalized (e.g., "Pending", "Running", "Succeeded", "Failed") to match Kubernetes core resource conventions.

**Examples from Kubernetes Core**:
- **Pod**: `"Pending"`, `"Running"`, `"Succeeded"`, `"Failed"` ✅
- **Job**: `"Pending"`, `"Running"`, `"Complete"`, `"Failed"` ✅
- **PersistentVolumeClaim**: `"Pending"`, `"Bound"`, `"Lost"` ✅

---

## 🚨 **Discovery & Resolution**

### **Issue Discovery**
**Date**: 2025-12-11
**Discovered By**: RemediationOrchestrator Team
**Context**: RO integration tests failed because SP used lowercase phases while RO expected capitalized values (per Kubernetes conventions).

**Impact**:
- RO controller couldn't detect SP completion
- 5/12 RO integration tests blocked
- RemediationRequest stuck in `Processing` phase indefinitely

### **Root Cause**
SignalProcessing phase constants were defined with lowercase values:
```go
// ❌ WRONG: Violated Kubernetes conventions
PhasePending   SignalProcessingPhase = "pending"
PhaseCompleted SignalProcessingPhase = "completed"
```

### **Resolution**
**Date**: 2025-12-11 (same day)
**Fixed By**: SP Team
**Verification**: All 194 SP unit tests passing, RO lifecycle test passing

---

## ✅ **Acceptance Criteria**

### **Service Level**
- [x] All phase constants use capitalized values
- [x] No mixed-case or lowercase phase values in CRD definitions
- [x] CRD enum validation matches constant values
- [x] All tests use phase constants (no hardcoded strings)

### **Integration Level**
- [x] Cross-service phase comparisons work correctly (e.g., RO checking SP phase)
- [x] Integration tests pass when services depend on each other's phases
- [x] Phase transitions trigger correct downstream actions

### **Documentation Level**
- [x] Phase format standard documented (this BR)
- [x] All service teams notified
- [x] kubectl examples use capitalized phases
- [x] Troubleshooting guides reference correct format

---

## 🔍 **Validation Commands**

### **Check CRD Phase Enum**
```bash
# Verify phase enum in generated CRD
grep -A 5 "enum:" config/crd/bases/*_signalprocessings.yaml
# Should show: - Pending, Enriching, Classifying, Categorizing, Completed, Failed
```

### **Check Controller Code**
```bash
# Find any hardcoded lowercase phase strings (should return nothing)
grep -r '"pending"\|"enriching"\|"completed"\|"failed"' \
  internal/controller/signalprocessing/ \
  --include="*.go" | grep -v "// "
```

### **Check Test Code**
```bash
# Verify tests use constants
grep -r 'Phase.*=' test/unit/signalprocessing/ \
  --include="*_test.go" | head -10
```

---

## 🔄 **Migration Guide**

### **For New Services**
When creating a new CRD controller:
1. Define phase type with capitalized enum values
2. Use constants for all phase assignments
3. Reference BR-COMMON-001 in code comments
4. Validate with integration tests

### **For Existing Services**
If lowercase phases discovered:
1. Create NOTICE document (follow `NOTICE_SP_PHASE_CAPITALIZATION_BUG.md` pattern)
2. Update phase constants to capitalized
3. Run `make manifests && make generate`
4. Update any hardcoded test strings
5. Verify integration tests with dependent services
6. Notify affected teams

### **For Service Consumers** (⭐ **VICEVERSA PATTERN**)

When consuming phase values from other services, use their typed constants directly:

```go
// ✅ CORRECT: Use source service's typed constants
import signalprocessingv1 "github.com/jordigilh/kubernaut/api/signalprocessing/v1alpha1"

switch sp.Status.Phase {
case string(signalprocessingv1.PhaseCompleted):  // Single source of truth
    // Handle completion
case string(signalprocessingv1.PhaseFailed):
    // Handle failure
}
```

```go
// ❌ WRONG: Hardcoded string literals
switch sp.Status.Phase {
case "Completed":  // Duplicates SP's definition
    // If SP changes, this breaks silently
}
```

**Benefits**:
- **Single Source of Truth**: Changes to upstream phase constants automatically propagate
- **Type Safety**: Compiler catches mismatches
- **Documentation**: Makes dependency explicit
- **Maintainability**: No need to track upstream changes manually

**When typed constants don't exist** (e.g., AIAnalysis, WorkflowExecution use plain `string`):
- Use string literals with reference comment:

```go
// Phase values per api/aianalysis/v1alpha1: Pending|Investigating|Analyzing|Completed|Failed
switch ai.Status.Phase {
case "Completed":
    // Handle completion
}
```

---

## 📞 **Cross-Team Coordination**

### **Notification Requirement**
When ANY service changes phase values:
1. Create individual team notifications (internal development reference, removed in v1.0)
2. Update this BR's Service Compliance Matrix
3. Run integration tests for ALL dependent services
4. Document migration timeline if breaking change

### **Dependency Chain**
```
Gateway → RO → SignalProcessing → RO → AIAnalysis → RO → WorkflowExecution
                                                 ↓
                                          Notification
```

Any phase format change affects the entire chain.

---

## 🎯 **Enforcement**

### **CI/CD Checks**
```bash
# Add to CI pipeline
# Fail build if lowercase phase enums detected in CRD
if grep -r 'Enum=.*[a-z].*pending\|[a-z].*completed\|[a-z].*failed' \
   api/*/v1alpha1/*_types.go; then
    echo "❌ ERROR: Lowercase phase values violate BR-COMMON-001"
    exit 1
fi
```

### **Code Review Checklist**
When reviewing CRD changes:
- [ ] Phase constants are capitalized
- [ ] Enum validation matches constants
- [ ] No hardcoded lowercase phase strings
- [ ] Tests use phase constants
- [ ] Documentation updated

---

## 📊 **Metrics**

### **Compliance Rate**
- **Target**: 100% of CRD controllers compliant
- **Current**: 5/5 CRD controllers with phase fields compliant ✅

### **Integration Stability**
- **Before**: 5/12 RO integration tests failing (phase mismatch)
- **After**: 9/12 RO integration tests passing (phase-related tests fixed)
- **Improvement**: 80% → 75% pass rate (phase issues resolved)

---

## 📚 **Related Authoritative Documents**

| Document | Authority | Purpose |
|----------|-----------|---------|
| 🏛️ **`RO_VICEVERSA_PATTERN_IMPLEMENTATION.md`** | **AUTHORITATIVE** | Mandatory pattern for consuming phase constants |
| `NOTICE_SP_PHASE_CAPITALIZATION_BUG.md` | Historical | Original bug report and resolution |
| `TEAM_NOTIFICATION_PHASE_STANDARD_*.md` | Informational | 7 team notifications |
| `docs/architecture/decisions/DD-CONTRACT-002-service-integration-contracts.md` | Reference | Service integration contracts |

---

## 🔖 **Version History**

| Version | Date | Change | Author |
|---------|------|--------|--------|
| 1.1 | 2026-03-03 | Added `WaitingForPropagation` EA phase (Issue #253, BR-EM-010.3) | EM Team |
| 1.0 | 2025-12-11 | Initial BR created after SP bug discovery | SP Team |

---

**Document Status**: 🏛️ **AUTHORITATIVE & ACTIVE**
**Authority Level**: GOVERNING STANDARD (supersedes all conflicting documentation)
**Created**: 2025-12-11
**Approved By**: SP Team (implementation), RO Team (validation), Architecture Team (governance)
**Enforcement**: MANDATORY for all CRD controllers with phase fields
**Scope**: System-wide - no exceptions without Architecture Team approval

