feat(labels): standardize automatic label creation to match ecosystem convention

@goal: WHOOSH-LABELS-004, WSH-CONSISTENCY - Ecosystem standardization Replace custom label set with standardized CHORUS ecosystem labels: - Add all 8 GitHub-standard labels (bug, duplicate, enhancement, etc.) - Fix bzzz-task color from #ff6b6b to #5319e7 for consistency - Remove custom priority labels and whoosh-monitored label - Maintain backward compatibility and error handling Changes: - Updated EnsureRequiredLabels() in internal/gitea/client.go - Added requirement traceability comments throughout - Updated integration points in internal/server/server.go - Created comprehensive decision record Benefits: - Consistent labeling across WHOOSH, CHORUS, KACHING repositories - Familiar GitHub-standard labels for better developer experience - Improved tool integration and issue management - Preserved bzzz-task automation for CHORUS workflow Fixes: WHOOSH issue #4 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-21 17:35:15 +10:00
parent 827e332e16
commit b4b1cce902
3 changed files with 212 additions and 21 deletions
--- a/docs/decisions/2025-09-21-standardized-label-ecosystem.md
+++ b/docs/decisions/2025-09-21-standardized-label-ecosystem.md
@@ -0,0 +1,165 @@
+# 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.
--- a/internal/gitea/client.go
+++ b/internal/gitea/client.go
@@ -433,49 +433,71 @@ func (c *Client) GetLabels(ctx context.Context, owner, repo string) ([]Label, er
 	return labels, nil
 }

+// @goal: WHOOSH-LABELS-004, WSH-CONSISTENCY - Ecosystem standardization
+// WHY: Ensures all CHORUS ecosystem repositories have consistent GitHub-standard labels
 // EnsureRequiredLabels ensures that required labels exist in the repository
 func (c *Client) EnsureRequiredLabels(ctx context.Context, owner, repo string) error {
+	// @goal: WHOOSH-LABELS-004 - Standardized label set matching WHOOSH repository conventions
+	// WHY: Provides consistent issue categorization across all CHORUS ecosystem repositories
 	requiredLabels := []CreateLabelRequest{
+		{
+			Name:        "bug",
+			Color:       "ee0701",
+			Description: "Something is not working",
+		},
 		{
 			Name:        "bzzz-task",
-			Color:       "ff6b6b",
-			Description: "Issues that should be converted to BZZZ tasks for CHORUS",
+			Color:       "5319e7", // @goal: WHOOSH-LABELS-004 - Corrected color to match ecosystem standard
+			Description: "CHORUS task for auto ingestion.",
 		},
 		{
-			Name:        "whoosh-monitored",
-			Color:       "4ecdc4", 
-			Description: "Repository is monitored by WHOOSH",
+			Name:        "duplicate",
+			Color:       "cccccc",
+			Description: "This issue or pull request already exists",
 		},
 		{
-			Name:        "priority-high",
-			Color:       "e74c3c",
-			Description: "High priority task for immediate attention",
+			Name:        "enhancement",
+			Color:       "84b6eb",
+			Description: "New feature",
 		},
 		{
-			Name:        "priority-medium",
-			Color:       "f39c12",
-			Description: "Medium priority task",
+			Name:        "help wanted",
+			Color:       "128a0c",
+			Description: "Need some help",
 		},
 		{
-			Name:        "priority-low",
-			Color:       "95a5a6",
-			Description: "Low priority task",
+			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",
 		},
 	}
 	
-	// Get existing labels
+	// @goal: WHOOSH-LABELS-004 - Check existing labels to avoid duplicates
+	// WHY: Prevents API errors from attempting to create labels that already exist
 	existingLabels, err := c.GetLabels(ctx, owner, repo)
 	if err != nil {
 		return fmt.Errorf("failed to get existing labels: %w", err)
 	}
-	
-	// Create a map of existing label names for quick lookup
+
+	// @goal: WHOOSH-LABELS-004 - Build lookup map for efficient duplicate checking
+	// WHY: O(1) lookup performance for label existence checking
 	existingLabelNames := make(map[string]bool)
 	for _, label := range existingLabels {
 		existingLabelNames[label.Name] = true
 	}
-	
-	// Create missing required labels
+
+	// @goal: WHOOSH-LABELS-004 - Create only missing standardized labels
+	// WHY: Ensures all repositories have consistent labeling without overwriting existing labels
 	for _, requiredLabel := range requiredLabels {
 		if !existingLabelNames[requiredLabel.Name] {
 			_, err := c.CreateLabel(ctx, owner, repo, requiredLabel)
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -2352,11 +2352,14 @@ func (s *Server) createRepositoryHandler(w http.ResponseWriter, r *http.Request)
 	}
 	
 	// Automatically create required labels in the Gitea repository
+	// @goal: WHOOSH-LABELS-004 - Automatic label creation on repository addition
+	// WHY: Ensures standardized ecosystem labels are available immediately for issue categorization
 	if req.SourceType == "gitea" && s.repoMonitor != nil && s.repoMonitor.GetGiteaClient() != nil {
 		log.Info().
 			Str("repository", fullName).
 			Msg("Creating required labels in Gitea repository")
-		
+
+		// @goal: WHOOSH-LABELS-004 - Apply standardized label set to new repository
 		err := s.repoMonitor.GetGiteaClient().EnsureRequiredLabels(context.Background(), req.Owner, req.Name)
 		if err != nil {
 			log.Warn().
@@ -2634,7 +2637,8 @@ func (s *Server) ensureRepositoryLabelsHandler(w http.ResponseWriter, r *http.Re
 		return
 	}
 	
-	// Ensure required labels exist
+	// @goal: WHOOSH-LABELS-004 - Manual label synchronization endpoint
+	// WHY: Allows updating existing repositories to standardized label set
 	err = s.repoMonitor.GetGiteaClient().EnsureRequiredLabels(context.Background(), owner, name)
 	if err != nil {
 		log.Error().