aios-core 2.1.5 → 2.2.0

package/.aios-core/development/tasks/consolidate-patterns.md

@@ -1,414 +1,414 @@
-# Consolidate Patterns Using Intelligent Clustering
-
-> Task ID: brad-consolidate-patterns
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: consolidatePatterns()
-responsável: Aria (Visionary)
-responsavel_type: Agente
-atomic_layer: Strategy
-
-**Entrada:**
-- campo: task
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Must be registered task
-
-- campo: parameters
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Valid task parameters
-
-- campo: mode
-  tipo: string
-  origem: User Input
-  obrigatório: false
-  validação: yolo|interactive|pre-flight
-
-**Saída:**
-- campo: execution_result
-  tipo: object
-  destino: Memory
-  persistido: false
-
-- campo: logs
-  tipo: array
-  destino: File (.ai/logs/*)
-  persistido: true
-
-- campo: state
-  tipo: object
-  destino: State management
-  persistido: true
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Task is registered; required parameters provided; dependencies met
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check task is registered; required parameters provided; dependencies met
-    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Task completed; exit code 0; expected outputs created
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify task completed; exit code 0; expected outputs created
-    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Task completed as expected; side effects documented
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert task completed as expected; side effects documented
-    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** task-runner
-  - **Purpose:** Task execution and orchestration
-  - **Source:** .aios-core/core/task-runner.js
-
-- **Tool:** logger
-  - **Purpose:** Execution logging and error tracking
-  - **Source:** .aios-core/utils/logger.js
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** execute-task.js
-  - **Purpose:** Generic task execution wrapper
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/execute-task.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Task Not Found
-   - **Cause:** Specified task not registered in system
-   - **Resolution:** Verify task name and registration
-   - **Recovery:** List available tasks, suggest similar
-
-2. **Error:** Invalid Parameters
-   - **Cause:** Task parameters do not match expected schema
-   - **Resolution:** Validate parameters against task definition
-   - **Recovery:** Provide parameter template, reject execution
-
-3. **Error:** Execution Timeout
-   - **Cause:** Task exceeds maximum execution time
-   - **Resolution:** Optimize task or increase timeout
-   - **Recovery:** Kill task, cleanup resources, log state
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 5-20 min (estimated)
-cost_estimated: $0.003-0.015
-token_usage: ~2,000-8,000 tokens
-```
-
-**Optimization Notes:**
-- Iterative analysis with depth limits; cache intermediate results; batch similar operations
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - automation
-  - workflow
-updated_at: 2025-11-17
-```
-
----
-
-
-## Description
-
-Reduce UI pattern redundancy by clustering similar patterns using intelligent algorithms (HSL color clustering at 5% threshold, semantic button grouping). Target: >80% reduction.
-
-## Prerequisites
-
-- Audit completed (*audit command run successfully)
-- .state.yaml exists with inventory results
-- pattern-inventory.json available
-
-## Workflow
-
-### Interactive Elicitation
-
-This task uses interactive elicitation to review consolidation decisions.
-
-1. **Load Audit Results**
-   - Read .state.yaml to get inventory data
-   - Display current redundancy metrics
-   - Confirm user wants to proceed with consolidation
-
-2. **Review Clustering Parameters**
-   - HSL threshold for colors (default: 5%)
-   - Ask if user has manual overrides (patterns that shouldn't merge)
-   - Confirm output directory
-
-3. **Present Consolidation Recommendations**
-   - Show before/after for each pattern type
-   - Ask for approval or adjustments
-   - Allow manual overrides before finalizing
-
-### Steps
-
-1. **Load Audit Data**
-   - Read .state.yaml for inventory results
-   - Validate audit phase completed
-   - Extract pattern counts and scan path
-   - Validation: State file exists and contains inventory data
-
-2. **Cluster Colors by HSL Similarity**
-   - Extract all unique colors from codebase
-   - Convert hex to HSL color space
-   - Group colors within 5% HSL threshold
-   - Select most-used color in each cluster as primary
-   - Identify semantic relationships (primary-dark as hover state)
-   - Validation: Color clusters created with usage counts
-
-3. **Cluster Button Patterns by Semantic Purpose**
-   - Extract button class names and patterns
-   - Analyze naming for semantic meaning (primary, secondary, danger, etc)
-   - Group functionally equivalent buttons
-   - Recommend minimal variant set (primary, secondary, destructive)
-   - Validation: Button consolidation map created
-
-4. **Consolidate Spacing Values**
-   - Extract all padding and margin values
-   - Identify base unit (4px or 8px)
-   - Propose spacing scale (xs, sm, md, lg, xl, 2xl, 3xl)
-   - Map existing values to scale
-   - Validation: Spacing scale generated
-
-5. **Consolidate Typography**
-   - Extract font sizes, weights, families
-   - Propose type scale (modular scale or fixed intervals)
-   - Consolidate similar weights (merge 500 and 600 if both exist)
-   - Recommend minimal font family set
-   - Validation: Typography scale created
-
-6. **Generate Consolidation Report**
-   - Create consolidation-report.md with before/after metrics
-   - Include reduction percentages for each pattern type
-   - Generate detailed cluster files (color-clusters.txt, button-consolidation.txt)
-   - Calculate overall reduction percentage
-   - Validation: Report shows >80% reduction or explain why not
-
-7. **Create Pattern Mapping**
-   - Generate old-to-new mapping for each pattern type
-   - Document which old patterns map to which new tokens
-   - Create migration guide snippets
-   - Validation: Complete mapping for all patterns
-
-8. **Update State File**
-   - Add consolidation section to .state.yaml
-   - Record before/after counts for all pattern types
-   - Update phase to "consolidation_complete"
-   - Log Brad's consolidation decisions
-   - Validation: State updated with consolidation data
-
-## Output
-
-- **consolidation-report.md**: Executive summary with reduction metrics
-- **color-clusters.txt**: Detailed color groupings with usage counts
-- **button-consolidation.txt**: Button semantic analysis and recommendations
-- **spacing-consolidation.txt**: Spacing scale proposal
-- **typography-consolidation.txt**: Typography scale proposal
-- **pattern-mapping.json**: Old pattern → new token mappings
-- **.state.yaml**: Updated with consolidation decisions
-
-### Output Format
-
-```yaml
-# .state.yaml consolidation section
-consolidation:
-  completed_at: "2025-10-27T12:30:00Z"
-  patterns_consolidated:
-    colors:
-      before: 89
-      after: 12
-      reduction: "86.5%"
-      clusters: 8
-    buttons:
-      before: 47
-      after: 3
-      reduction: "93.6%"
-      variants: ["primary", "secondary", "destructive"]
-    spacing:
-      before: 19
-      after: 7
-      reduction: "63.2%"
-      scale: ["xs", "sm", "md", "lg", "xl", "2xl", "3xl"]
-    typography:
-      before: 21
-      after: 10
-      reduction: "52.4%"
-  overall_reduction: "81.8%"
-  target_met: true
-```
-
-## Success Criteria
-
-- [ ] >80% overall pattern reduction achieved
-- [ ] Color clustering uses HSL similarity (not just hex distance)
-- [ ] Button variants identified by semantic purpose
-- [ ] Spacing scale based on consistent base unit
-- [ ] Most-used patterns preserved as primary tokens
-- [ ] All consolidation decisions documented with rationale
-- [ ] User can review and override before finalizing
-
-## Error Handling
-
-- **No audit data found**: Exit with message to run *audit first
-- **Insufficient patterns to consolidate**: Report that codebase is already clean
-- **Cannot achieve 80% reduction**: Explain why and show actual reduction achieved
-- **Invalid state file**: Attempt to recover from backup or prompt re-audit
-
-## Security Considerations
-
-- Read-only analysis of patterns (no code modification)
-- Validate user overrides to prevent injection
-- Handle malformed color values safely
-- Backup state file before overwriting
-
-## Examples
-
-### Example 1: Successful Consolidation
-
-```bash
-*consolidate
-```
-
-Output:
-```
-🎨 CONSOLIDATING COLORS...
-Found 89 unique colors
-Clustering with 5% HSL threshold...
-
-CLUSTER 1 - Primary Blues (4 → 1):
-  #0066CC (234 uses) <- KEEP
-  #0065CB, #0067CD, #0064CA (merge)
-
-CLUSTER 2 - Error Reds (3 → 1):
-  #DC2626 (89 uses) <- KEEP
-  #DB2525, #DD2727 (merge)
-
-📊 CONSOLIDATION SUMMARY:
-| Pattern    | Before | After | Reduction |
-|------------|--------|-------|-----------|
-| Colors     | 89     | 12    | 86.5%     |
-| Buttons    | 47     | 3     | 93.6%     |
-| Spacing    | 19     | 7     | 63.2%     |
-| Typography | 21     | 10    | 52.4%     |
-| TOTAL      | 176    | 32    | 81.8%     |
-
-✅ TARGET MET: >80% reduction achieved
-✅ Report saved: outputs/design-system/my-app/consolidation/consolidation-report.md
-```
-
-### Example 2: User Override
-
-```bash
-*consolidate
-
-Brad: "Merge #0066CC and #0052A3?"
-User: "No, #0052A3 is intentional hover state"
-Brad: "Override recorded. Keeping both."
-```
-
-## Notes
-
-- HSL color space provides perceptual similarity (better than RGB/hex distance)
-- Most-used pattern in each cluster becomes the canonical token
-- Semantic button analysis looks for keywords: primary, main, secondary, default, danger, delete, destructive
-- Spacing scale should use consistent base unit (4px or 8px)
-- Manual overrides are respected and documented
-- Run this after every audit to prevent pattern regression
-- Brad says: "Numbers don't lie. 82% reduction = real savings."
+# Consolidate Patterns Using Intelligent Clustering
+
+> Task ID: brad-consolidate-patterns
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: consolidatePatterns()
+responsável: Aria (Visionary)
+responsavel_type: Agente
+atomic_layer: Strategy
+
+**Entrada:**
+- campo: task
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be registered task
+
+- campo: parameters
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid task parameters
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: execution_result
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: logs
+  tipo: array
+  destino: File (.ai/logs/*)
+  persistido: true
+
+- campo: state
+  tipo: object
+  destino: State management
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** task-runner
+  - **Purpose:** Task execution and orchestration
+  - **Source:** .aios-core/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .aios-core/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-20 min (estimated)
+cost_estimated: $0.003-0.015
+token_usage: ~2,000-8,000 tokens
+```
+
+**Optimization Notes:**
+- Iterative analysis with depth limits; cache intermediate results; batch similar operations
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Description
+
+Reduce UI pattern redundancy by clustering similar patterns using intelligent algorithms (HSL color clustering at 5% threshold, semantic button grouping). Target: >80% reduction.
+
+## Prerequisites
+
+- Audit completed (*audit command run successfully)
+- .state.yaml exists with inventory results
+- pattern-inventory.json available
+
+## Workflow
+
+### Interactive Elicitation
+
+This task uses interactive elicitation to review consolidation decisions.
+
+1. **Load Audit Results**
+   - Read .state.yaml to get inventory data
+   - Display current redundancy metrics
+   - Confirm user wants to proceed with consolidation
+
+2. **Review Clustering Parameters**
+   - HSL threshold for colors (default: 5%)
+   - Ask if user has manual overrides (patterns that shouldn't merge)
+   - Confirm output directory
+
+3. **Present Consolidation Recommendations**
+   - Show before/after for each pattern type
+   - Ask for approval or adjustments
+   - Allow manual overrides before finalizing
+
+### Steps
+
+1. **Load Audit Data**
+   - Read .state.yaml for inventory results
+   - Validate audit phase completed
+   - Extract pattern counts and scan path
+   - Validation: State file exists and contains inventory data
+
+2. **Cluster Colors by HSL Similarity**
+   - Extract all unique colors from codebase
+   - Convert hex to HSL color space
+   - Group colors within 5% HSL threshold
+   - Select most-used color in each cluster as primary
+   - Identify semantic relationships (primary-dark as hover state)
+   - Validation: Color clusters created with usage counts
+
+3. **Cluster Button Patterns by Semantic Purpose**
+   - Extract button class names and patterns
+   - Analyze naming for semantic meaning (primary, secondary, danger, etc)
+   - Group functionally equivalent buttons
+   - Recommend minimal variant set (primary, secondary, destructive)
+   - Validation: Button consolidation map created
+
+4. **Consolidate Spacing Values**
+   - Extract all padding and margin values
+   - Identify base unit (4px or 8px)
+   - Propose spacing scale (xs, sm, md, lg, xl, 2xl, 3xl)
+   - Map existing values to scale
+   - Validation: Spacing scale generated
+
+5. **Consolidate Typography**
+   - Extract font sizes, weights, families
+   - Propose type scale (modular scale or fixed intervals)
+   - Consolidate similar weights (merge 500 and 600 if both exist)
+   - Recommend minimal font family set
+   - Validation: Typography scale created
+
+6. **Generate Consolidation Report**
+   - Create consolidation-report.md with before/after metrics
+   - Include reduction percentages for each pattern type
+   - Generate detailed cluster files (color-clusters.txt, button-consolidation.txt)
+   - Calculate overall reduction percentage
+   - Validation: Report shows >80% reduction or explain why not
+
+7. **Create Pattern Mapping**
+   - Generate old-to-new mapping for each pattern type
+   - Document which old patterns map to which new tokens
+   - Create migration guide snippets
+   - Validation: Complete mapping for all patterns
+
+8. **Update State File**
+   - Add consolidation section to .state.yaml
+   - Record before/after counts for all pattern types
+   - Update phase to "consolidation_complete"
+   - Log Brad's consolidation decisions
+   - Validation: State updated with consolidation data
+
+## Output
+
+- **consolidation-report.md**: Executive summary with reduction metrics
+- **color-clusters.txt**: Detailed color groupings with usage counts
+- **button-consolidation.txt**: Button semantic analysis and recommendations
+- **spacing-consolidation.txt**: Spacing scale proposal
+- **typography-consolidation.txt**: Typography scale proposal
+- **pattern-mapping.json**: Old pattern → new token mappings
+- **.state.yaml**: Updated with consolidation decisions
+
+### Output Format
+
+```yaml
+# .state.yaml consolidation section
+consolidation:
+  completed_at: "2025-10-27T12:30:00Z"
+  patterns_consolidated:
+    colors:
+      before: 89
+      after: 12
+      reduction: "86.5%"
+      clusters: 8
+    buttons:
+      before: 47
+      after: 3
+      reduction: "93.6%"
+      variants: ["primary", "secondary", "destructive"]
+    spacing:
+      before: 19
+      after: 7
+      reduction: "63.2%"
+      scale: ["xs", "sm", "md", "lg", "xl", "2xl", "3xl"]
+    typography:
+      before: 21
+      after: 10
+      reduction: "52.4%"
+  overall_reduction: "81.8%"
+  target_met: true
+```
+
+## Success Criteria
+
+- [ ] >80% overall pattern reduction achieved
+- [ ] Color clustering uses HSL similarity (not just hex distance)
+- [ ] Button variants identified by semantic purpose
+- [ ] Spacing scale based on consistent base unit
+- [ ] Most-used patterns preserved as primary tokens
+- [ ] All consolidation decisions documented with rationale
+- [ ] User can review and override before finalizing
+
+## Error Handling
+
+- **No audit data found**: Exit with message to run *audit first
+- **Insufficient patterns to consolidate**: Report that codebase is already clean
+- **Cannot achieve 80% reduction**: Explain why and show actual reduction achieved
+- **Invalid state file**: Attempt to recover from backup or prompt re-audit
+
+## Security Considerations
+
+- Read-only analysis of patterns (no code modification)
+- Validate user overrides to prevent injection
+- Handle malformed color values safely
+- Backup state file before overwriting
+
+## Examples
+
+### Example 1: Successful Consolidation
+
+```bash
+*consolidate
+```
+
+Output:
+```
+🎨 CONSOLIDATING COLORS...
+Found 89 unique colors
+Clustering with 5% HSL threshold...
+
+CLUSTER 1 - Primary Blues (4 → 1):
+  #0066CC (234 uses) <- KEEP
+  #0065CB, #0067CD, #0064CA (merge)
+
+CLUSTER 2 - Error Reds (3 → 1):
+  #DC2626 (89 uses) <- KEEP
+  #DB2525, #DD2727 (merge)
+
+📊 CONSOLIDATION SUMMARY:
+| Pattern    | Before | After | Reduction |
+|------------|--------|-------|-----------|
+| Colors     | 89     | 12    | 86.5%     |
+| Buttons    | 47     | 3     | 93.6%     |
+| Spacing    | 19     | 7     | 63.2%     |
+| Typography | 21     | 10    | 52.4%     |
+| TOTAL      | 176    | 32    | 81.8%     |
+
+✅ TARGET MET: >80% reduction achieved
+✅ Report saved: outputs/design-system/my-app/consolidation/consolidation-report.md
+```
+
+### Example 2: User Override
+
+```bash
+*consolidate
+
+Brad: "Merge #0066CC and #0052A3?"
+User: "No, #0052A3 is intentional hover state"
+Brad: "Override recorded. Keeping both."
+```
+
+## Notes
+
+- HSL color space provides perceptual similarity (better than RGB/hex distance)
+- Most-used pattern in each cluster becomes the canonical token
+- Semantic button analysis looks for keywords: primary, main, secondary, default, danger, delete, destructive
+- Spacing scale should use consistent base unit (4px or 8px)
+- Manual overrides are respected and documented
+- Run this after every audit to prevent pattern regression
+- Brad says: "Numbers don't lie. 82% reduction = real savings."