# DR: Standardized Label Ecosystem for CHORUS Repositories

Date: 2025-09-21
Status: Accepted
UCXL: ucxl://ops:planner@WHOOSH:label-management/DRs/2025-09-21-standardized-label-ecosystem.md

## Problem

WHOOSH automatically creates labels when repositories are added to the monitoring system, but the current label set differs from the standardized conventions used across the CHORUS ecosystem (WHOOSH, CHORUS, KACHING repositories). This creates inconsistency in issue management and developer experience across the ecosystem.

### Current State Analysis

**WHOOSH Auto-Created Labels** (Prior Implementation):
- `bzzz-task` (#ff6b6b) - Issues for CHORUS task conversion
- `whoosh-monitored` (#4ecdc4) - Repository monitoring indicator
- `priority-high` (#e74c3c) - High priority tasks
- `priority-medium` (#f39c12) - Medium priority tasks
- `priority-low` (#95a5a6) - Low priority tasks

**Ecosystem Standard Labels** (WHOOSH Repository):
- `bug` (#ee0701) - Something is not working
- `bzzz-task` (#5319e7) - CHORUS task for auto ingestion
- `duplicate` (#cccccc) - This issue or pull request already exists
- `enhancement` (#84b6eb) - New feature
- `help wanted` (#128a0c) - Need some help
- `invalid` (#e6e6e6) - Something is wrong
- `question` (#cc317c) - More information is needed
- `wontfix` (#ffffff) - This won't be fixed

## Options Considered

### Option 1: Maintain Current Custom Labels
**Pros:**
- No changes required to existing code
- Maintains WHOOSH-specific functionality (priority labels)
- No risk of breaking existing repositories

**Cons:**
- Inconsistent with ecosystem standards
- Poor developer experience (unfamiliar labels)
- Limits tool integration with GitHub-standard workflows
- Creates confusion when moving between repositories

### Option 2: Adopt GitHub Standard Labels Only
**Pros:**
- Maximum compatibility with external tools
- Familiar to all developers
- Industry standard approach

**Cons:**
- Loses WHOOSH-specific functionality (priority classification)
- May not adequately support CHORUS workflow automation
- No `bzzz-task` integration for automated task creation

### Option 3: Hybrid Approach - Ecosystem Standards + Optional Extensions (Chosen)
**Pros:**
- Consistent with ecosystem-wide conventions
- Maintains GitHub-standard familiarity
- Preserves `bzzz-task` automation integration
- Allows future addition of priority labels as enhancement
- Provides clear migration path

**Cons:**
- Requires updating existing implementation
- Existing repositories may have inconsistent labels until sync

## Decision

Adopt the standardized CHORUS ecosystem label set as the default for all repositories added to WHOOSH monitoring. This includes all 8 labels currently used in the WHOOSH repository itself.

### Implementation Details

**Updated Label Set:**
```go
requiredLabels := []CreateLabelRequest{
    {Name: "bug", Color: "ee0701", Description: "Something is not working"},
    {Name: "bzzz-task", Color: "5319e7", Description: "CHORUS task for auto ingestion."},
    {Name: "duplicate", Color: "cccccc", Description: "This issue or pull request already exists"},
    {Name: "enhancement", Color: "84b6eb", Description: "New feature"},
    {Name: "help wanted", Color: "128a0c", Description: "Need some help"},
    {Name: "invalid", Color: "e6e6e6", Description: "Something is wrong"},
    {Name: "question", Color: "cc317c", Description: "More information is needed"},
    {Name: "wontfix", Color: "ffffff", Description: "This won't be fixed"},
}
```

**Key Changes:**
1. **Color Correction**: `bzzz-task` color updated from `#ff6b6b` to `#5319e7`
2. **Standard Labels Added**: All GitHub-standard issue management labels
3. **Custom Labels Removed**: `whoosh-monitored`, priority labels (can be re-added as enhancement)
4. **Ecosystem Alignment**: Matches WHOOSH, CHORUS, KACHING repository standards

### Affected Components

**Automatic Integration:**
- `internal/gitea/client.go:EnsureRequiredLabels()` - Core label creation logic
- `internal/server/server.go:createRepositoryHandler` - Automatic execution on repo addition
- `internal/server/server.go:ensureRepositoryLabelsHandler` - Manual sync endpoint

**Requirement Traceability:**
- All modified functions include `@goal: WHOOSH-LABELS-004` tags
- Inline comments explain rationale and ecosystem alignment
- Full traceability from issue #4 through implementation

## Impact Assessment

### Positive Impacts
1. **Ecosystem Consistency**: All CHORUS repositories have identical label conventions
2. **Developer Experience**: Familiar GitHub-standard labels reduce cognitive overhead
3. **Tool Integration**: Better compatibility with external issue management tools
4. **Maintenance**: Simplified label management across multiple repositories
5. **Automation**: Preserved `bzzz-task` integration for CHORUS workflow automation

### Risk Mitigation
1. **Backward Compatibility**: Existing repositories continue to function with old labels
2. **Graceful Degradation**: Label creation failures don't block repository monitoring
3. **Manual Sync**: API endpoint available for updating existing repositories
4. **Rollback Plan**: Can revert to previous label set if critical issues arise

### Migration Strategy
1. **New Repositories**: Automatically receive standardized labels
2. **Existing Repositories**: Manual sync via API endpoint as needed
3. **Monitoring**: No impact on issue detection or monitoring functionality
4. **Documentation**: Update guides to reflect new label conventions

## Future Enhancements

### Planned Extensions
1. **Priority Labels**: Add as optional/configurable feature
2. **Repository-Specific Labels**: Support for custom labels per repository type
3. **Label Validation**: Automated checking to ensure labels remain consistent
4. **Migration Tools**: Bulk update tools for existing repository sets

### Configuration Options
Future consideration for making label sets configurable:
```yaml
label_sets:
  standard: [bug, enhancement, question, ...]
  priority: [priority-high, priority-medium, priority-low]
  monitoring: [whoosh-monitored, status-active, ...]
```

## Evidence and References

- **Issue**: WHOOSH #4 - Standardize Automatic Label Creation to Match Ecosystem Convention
- **Implementation**: `internal/gitea/client.go`, `internal/server/server.go`
- **Manual Verification**: Successfully tested label creation on CHORUS and KACHING repositories
- **Ecosystem Audit**: Confirmed WHOOSH, CHORUS, KACHING all use identical label sets post-implementation

## Acceptance Criteria Validation

✅ **EnsureRequiredLabels()** creates all 8 standardized labels
✅ **bzzz-task** label uses correct color (#5319e7)
✅ **All labels** match WHOOSH repository standards exactly
✅ **Automatic creation** works on repository addition
✅ **Manual sync** endpoint functions correctly
✅ **No breaking changes** to existing monitoring functionality
✅ **Inline comments** include @goal: traceability tags
✅ **Decision record** documents rationale and implementation

## Conclusion

This change aligns WHOOSH with ecosystem-wide conventions while preserving essential automation functionality. The standardized approach improves developer experience and tool compatibility while maintaining the flexibility to add domain-specific labels as future enhancements.

The implementation maintains backward compatibility and provides clear migration paths, ensuring a smooth transition to the new standardized approach.