aiox-core 5.0.3 → 5.0.4

package/pro/squads/design/tasks/ds-context-contract.md

@@ -1,194 +1,194 @@
-# Context Contract for Design Tasks
-
-> Task ID: ds-context-contract
-> Agent: Design Chief
-> Version: 1.0.0
-> Heuristic: #10 - IA nasce do zero a cada janela
-
-## Description
-
-Definir contrato de contexto mínimo que toda task de design deve receber para executar sem ambiguidade.
-
-**Princípio:** IA não tem memória entre sessões. Contexto explícito > implícito.
-
----
-
-## Context Contract Schema
-
-Toda task de design DEVE receber:
-
-```yaml
-# Obrigatório
-context:
-  project:
-    name: string              # Nome do projeto
-    type: enum                # "greenfield" | "brownfield" | "migration"
-    stack: array              # ["react", "tailwind", "shadcn"]
-
-  design_system:
-    tokens_path: string       # Path para design-tokens-spec.yaml
-    registry_path: string     # Path para registry.json
-    metadata_path: string     # Path para metadata/components.json
-
-  scope:
-    components: array         # Componentes envolvidos
-    tokens: array             # Tokens envolvidos
-    surfaces: array           # S1, S2, S3
-
-# Opcional
-  constraints:
-    wcag_level: enum          # "A" | "AA" | "AAA"
-    browser_support: array    # ["chrome", "firefox", "safari"]
-    breakpoints: array        # ["mobile", "tablet", "desktop"]
-
-  references:
-    figma_url: string
-    storybook_url: string
-    production_url: string
-```
-
----
-
-## Implementation
-
-## Execution Steps
-
-1. Definir contrato de campos obrigatórios/opcionais para a task alvo.
-2. Injetar seção `Context Requirements` no header da task.
-3. Carregar defaults do contexto via loader padrão.
-4. Validar pré-condições de contexto antes da execução da task.
-5. Registrar gaps e bloquear execução quando campo obrigatório estiver ausente.
-
-### 1. Task Header Template
-
-Todas as tasks em `squads/design/tasks/` devem incluir:
-
-```markdown
-## Context Requirements
-
-Este task requer o seguinte contexto:
-
-| Campo | Obrigatório | Default |
-|-------|-------------|---------|
-| project.name | ✅ | — |
-| project.type | ✅ | — |
-| design_system.tokens_path | ✅ | `squads/design/data/design-tokens-spec.yaml` |
-| design_system.registry_path | ✅ | `workspace/ui/registry.json` |
-| scope.components | ✅ | — |
-| constraints.wcag_level | ❌ | "AA" |
-```
-
-### 2. Context Loader Script
-
-```javascript
-// squads/design/scripts/load-context.cjs
-module.exports = {
-  loadContext(taskId) {
-    return {
-      design_system: {
-        tokens_path: 'squads/design/data/design-tokens-spec.yaml',
-        registry_path: 'workspace/ui/registry.json',
-        metadata_path: 'workspace/domains/design-system/metadata/components.json',
-        glossary_path: 'workspace/domains/design-system/glossary.yaml'
-      },
-      defaults: {
-        wcag_level: 'AA',
-        surfaces: ['S1', 'S2']
-      }
-    };
-  }
-};
-```
-
-### 3. Validation
-
-Antes de executar qualquer task:
-
-```yaml
-validation:
-  - check: context.project.name exists
-    error: "Project name is required"
-  - check: context.scope.components is not empty
-    error: "At least one component must be in scope"
-  - check: context.design_system.tokens_path is readable
-    error: "Tokens file not found"
-```
-
----
-
-## Usage Example
-
-```markdown
-## Invocação com Contexto
-
-@brad-frost Execute ds-build-component
-
-**Context:**
-- project.name: "Lendário App"
-- project.type: "brownfield"
-- scope.components: ["Button", "Input"]
-- scope.surfaces: ["S1"]
-- constraints.wcag_level: "AA"
-```
-
----
-
-## Default Context File
-
-Criar arquivo de contexto padrão por projeto:
-
-```yaml
-# workspace/domains/design-system/context.yaml
-version: "1.0.0"
-project:
-  name: "Lendário"
-  type: "brownfield"
-  stack: ["next.js", "tailwind", "shadcn"]
-
-design_system:
-  tokens_path: "squads/design/data/design-tokens-spec.yaml"
-  registry_path: "workspace/ui/registry.json"
-  metadata_path: "workspace/domains/design-system/metadata/components.json"
-  glossary_path: "workspace/domains/design-system/glossary.yaml"
-
-defaults:
-  wcag_level: "AA"
-  surfaces: ["S1", "S2"]
-  breakpoints: ["mobile", "tablet", "desktop"]
-```
-
----
-
-## Quality Gates
-
-- [ ] Toda task tem seção "Context Requirements"
-- [ ] Context loader script existe e funciona
-- [ ] Default context file existe
-- [ ] Validation falha graciosamente com mensagens claras
-
-## Output
-
-- `workspace/domains/design-system/context.yaml` validado contra o contrato
-- Matriz de campos obrigatórios/opcionais por task (`Context Requirements`) atualizada
-- Relatório de conformidade de contexto por task (pass/fail + gaps)
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-migration-readiness-checklist.md`
-
----
-
-*Task criada: 2026-02-16*
-*Squad: Design*
-
-
-## Process Guards
-- **Execution Type:** `Hybrid`
-- **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `design-system`
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.
-
-## Success Criteria
-- [ ] Output artifact(s) generated and referenced.
-- [ ] Validation checks executed with evidence.
-- [ ] Next-step dependencies documented.
+# Context Contract for Design Tasks
+
+> Task ID: ds-context-contract
+> Agent: Design Chief
+> Version: 1.0.0
+> Heuristic: #10 - IA nasce do zero a cada janela
+
+## Description
+
+Definir contrato de contexto mínimo que toda task de design deve receber para executar sem ambiguidade.
+
+**Princípio:** IA não tem memória entre sessões. Contexto explícito > implícito.
+
+---
+
+## Context Contract Schema
+
+Toda task de design DEVE receber:
+
+```yaml
+# Obrigatório
+context:
+  project:
+    name: string              # Nome do projeto
+    type: enum                # "greenfield" | "brownfield" | "migration"
+    stack: array              # ["react", "tailwind", "shadcn"]
+
+  design_system:
+    tokens_path: string       # Path para design-tokens-spec.yaml
+    registry_path: string     # Path para registry.json
+    metadata_path: string     # Path para metadata/components.json
+
+  scope:
+    components: array         # Componentes envolvidos
+    tokens: array             # Tokens envolvidos
+    surfaces: array           # S1, S2, S3
+
+# Opcional
+  constraints:
+    wcag_level: enum          # "A" | "AA" | "AAA"
+    browser_support: array    # ["chrome", "firefox", "safari"]
+    breakpoints: array        # ["mobile", "tablet", "desktop"]
+
+  references:
+    figma_url: string
+    storybook_url: string
+    production_url: string
+```
+
+---
+
+## Implementation
+
+## Execution Steps
+
+1. Definir contrato de campos obrigatórios/opcionais para a task alvo.
+2. Injetar seção `Context Requirements` no header da task.
+3. Carregar defaults do contexto via loader padrão.
+4. Validar pré-condições de contexto antes da execução da task.
+5. Registrar gaps e bloquear execução quando campo obrigatório estiver ausente.
+
+### 1. Task Header Template
+
+Todas as tasks em `squads/design/tasks/` devem incluir:
+
+```markdown
+## Context Requirements
+
+Este task requer o seguinte contexto:
+
+| Campo | Obrigatório | Default |
+|-------|-------------|---------|
+| project.name | ✅ | — |
+| project.type | ✅ | — |
+| design_system.tokens_path | ✅ | `squads/design/data/design-tokens-spec.yaml` |
+| design_system.registry_path | ✅ | `workspace/ui/registry.json` |
+| scope.components | ✅ | — |
+| constraints.wcag_level | ❌ | "AA" |
+```
+
+### 2. Context Loader Script
+
+```javascript
+// squads/design/scripts/load-context.cjs
+module.exports = {
+  loadContext(taskId) {
+    return {
+      design_system: {
+        tokens_path: 'squads/design/data/design-tokens-spec.yaml',
+        registry_path: 'workspace/ui/registry.json',
+        metadata_path: 'workspace/domains/design-system/metadata/components.json',
+        glossary_path: 'workspace/domains/design-system/glossary.yaml'
+      },
+      defaults: {
+        wcag_level: 'AA',
+        surfaces: ['S1', 'S2']
+      }
+    };
+  }
+};
+```
+
+### 3. Validation
+
+Antes de executar qualquer task:
+
+```yaml
+validation:
+  - check: context.project.name exists
+    error: "Project name is required"
+  - check: context.scope.components is not empty
+    error: "At least one component must be in scope"
+  - check: context.design_system.tokens_path is readable
+    error: "Tokens file not found"
+```
+
+---
+
+## Usage Example
+
+```markdown
+## Invocação com Contexto
+
+@brad-frost Execute ds-build-component
+
+**Context:**
+- project.name: "Lendário App"
+- project.type: "brownfield"
+- scope.components: ["Button", "Input"]
+- scope.surfaces: ["S1"]
+- constraints.wcag_level: "AA"
+```
+
+---
+
+## Default Context File
+
+Criar arquivo de contexto padrão por projeto:
+
+```yaml
+# workspace/domains/design-system/context.yaml
+version: "1.0.0"
+project:
+  name: "Lendário"
+  type: "brownfield"
+  stack: ["next.js", "tailwind", "shadcn"]
+
+design_system:
+  tokens_path: "squads/design/data/design-tokens-spec.yaml"
+  registry_path: "workspace/ui/registry.json"
+  metadata_path: "workspace/domains/design-system/metadata/components.json"
+  glossary_path: "workspace/domains/design-system/glossary.yaml"
+
+defaults:
+  wcag_level: "AA"
+  surfaces: ["S1", "S2"]
+  breakpoints: ["mobile", "tablet", "desktop"]
+```
+
+---
+
+## Quality Gates
+
+- [ ] Toda task tem seção "Context Requirements"
+- [ ] Context loader script existe e funciona
+- [ ] Default context file existe
+- [ ] Validation falha graciosamente com mensagens claras
+
+## Output
+
+- `workspace/domains/design-system/context.yaml` validado contra o contrato
+- Matriz de campos obrigatórios/opcionais por task (`Context Requirements`) atualizada
+- Relatório de conformidade de contexto por task (pass/fail + gaps)
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-migration-readiness-checklist.md`
+
+---
+
+*Task criada: 2026-02-16*
+*Squad: Design*
+
+
+## Process Guards
+- **Execution Type:** `Hybrid`
+- **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `design-system`
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.
+
+## Success Criteria
+- [ ] Output artifact(s) generated and referenced.
+- [ ] Validation checks executed with evidence.
+- [ ] Next-step dependencies documented.

package/pro/squads/design/tasks/ds-critical-eye-compare.md

@@ -1,130 +1,130 @@
-# Critical Eye — Compare and Rank Variants Within Category
-
-> Task ID: ds-critical-eye-compare
-> Agent: Brad Frost (Design System Architect)
-> Version: 1.0.0
-> v4.0-compatible: true
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[ds-critical-eye-score]` · enables: `[ds-critical-eye-decide]` · workflow: `critical-eye`
-
-## Description
-
-Within each category, rank all scored variants from highest to lowest total score. Apply the tiebreaker rule: when two variants are within a 10% margin, the one with higher breadth wins (network effect favors broader adoption — Nathan Curtis). Identify the top candidate per category for potential CANONICAL promotion.
-
-## Output Schema
-- **produces:** `outputs/design-system/critical-eye/cycle-{N}/rankings.json`
-- **format:** JSON — ranked variants per category with comparison matrix
-- **consumed_by:** ds-critical-eye-decide
-
-## Prerequisites
-
-- Scored variants output from `ds-critical-eye-score` available
-- `critical-eye-scoring-rules.yaml` loaded (for tiebreaker config)
-
-## Workflow
-
-### Steps
-
-1. **Load Scored Variants**
-   - Read `scored.json` from previous step
-   - Group variants by category (should already be grouped from inventory)
-   - Exclude any variants with lifecycle = `REJECT` (a11y blocker)
-   - Check: scored variants loaded, REJECT variants excluded from ranking
-
-2. **Sort Within Each Category**
-   - For each category:
-     - Sort variants by `scores.total` descending
-     - Record rank position (1 = highest)
-   - Check: all categories sorted
-
-3. **Apply Tiebreaker Rule**
-   - For each pair of adjacent-ranked variants in a category:
-     - Calculate margin: `abs(score_a - score_b) / max(score_a, score_b) * 100`
-     - If margin <= 10%:
-       - Compare `scores.breadth`
-       - Higher breadth wins the higher rank
-       - Log: "Tiebreaker applied: {winner} (breadth={N}) beats {loser} (breadth={N}) within {margin}% margin"
-   - Authority: Nathan Curtis — network effect favors broader adoption
-   - Check: all ties resolved, tiebreaker applications logged
-
-4. **Identify Category Leaders**
-   - For each category:
-     - The rank-1 variant is the "category leader"
-     - If leader's `total_score >= 80` AND it's the highest in category → eligible for CANONICAL
-     - If leader's `total_score >= 60` → eligible for STABLE
-     - If leader's `total_score >= 40` → eligible for EXPERIMENTAL
-   - Check: category leaders identified with eligibility flags
-
-5. **Build Comparison Matrix**
-   - For each category with 2+ variants:
-     - Create head-to-head comparison showing which variant wins in each dimension
-     - Structure:
-       ```json
-       {
-         "category": "base",
-         "component": "button",
-         "variants": ["button-shared-v1", "button-clickmax-v2"],
-         "dimension_winners": {
-           "breadth": "button-shared-v1",
-           "quality": "button-clickmax-v2",
-           "consistency": "button-shared-v1",
-           "maturity": "button-shared-v1",
-           "simplicity": "button-clickmax-v2"
-         },
-         "overall_winner": "button-shared-v1",
-         "margin": "12%"
-       }
-       ```
-   - For categories with 1 variant: mark as "uncontested"
-   - Check: comparison matrix built for all multi-variant categories
-
-6. **Calculate Category Health**
-   - For each category:
-     - `avg_score`: average total score of all variants
-     - `max_score`: highest score
-     - `min_score`: lowest score
-     - `spread`: max - min
-     - `variant_count`: total variants
-     - `has_canonical`: boolean (any variant currently CANONICAL?)
-   - Categories with `avg_score < 40` flagged as "needs attention"
-   - Check: health metrics calculated for all categories
-
-7. **Generate Rankings Output**
-   - Create `rankings.json`:
-     ```json
-     {
-       "cycle": N,
-       "timestamp": "ISO-8601",
-       "categories": {
-         "base": {
-           "rankings": [...sorted variants with rank...],
-           "leader": { "id": "...", "score": N, "eligibility": "..." },
-           "comparisons": [...comparison matrices...],
-           "health": { "avg": N, "max": N, "min": N, "spread": N, "count": N }
-         },
-         ...
-       },
-       "tiebreakers_applied": [...],
-       "categories_needing_attention": [...]
-     }
-     ```
-   - Check: output valid JSON, all categories represented
-
-## Failure Handling
-
-- **Scored variants not found:** Abort with "Run ds-critical-eye-score first."
-- **Empty category:** Warn but continue (category present with 0 variants)
-- **All variants REJECTED in category:** Flag category as "blocked — all variants failed a11y"
-
-## Success Criteria
-
-- [ ] All variants ranked within their category
-- [ ] Tiebreaker rule applied where scores within 10%
-- [ ] Category leaders identified with eligibility flags
-- [ ] Comparison matrix built for multi-variant categories
-- [ ] Category health metrics calculated
-- [ ] Rankings JSON output complete and valid
-
-## Related Checklists
-
-- `squads/design/checklists/ds-critical-eye-review-checklist.md`
+# Critical Eye — Compare and Rank Variants Within Category
+
+> Task ID: ds-critical-eye-compare
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[ds-critical-eye-score]` · enables: `[ds-critical-eye-decide]` · workflow: `critical-eye`
+
+## Description
+
+Within each category, rank all scored variants from highest to lowest total score. Apply the tiebreaker rule: when two variants are within a 10% margin, the one with higher breadth wins (network effect favors broader adoption — Nathan Curtis). Identify the top candidate per category for potential CANONICAL promotion.
+
+## Output Schema
+- **produces:** `outputs/design-system/critical-eye/cycle-{N}/rankings.json`
+- **format:** JSON — ranked variants per category with comparison matrix
+- **consumed_by:** ds-critical-eye-decide
+
+## Prerequisites
+
+- Scored variants output from `ds-critical-eye-score` available
+- `critical-eye-scoring-rules.yaml` loaded (for tiebreaker config)
+
+## Workflow
+
+### Steps
+
+1. **Load Scored Variants**
+   - Read `scored.json` from previous step
+   - Group variants by category (should already be grouped from inventory)
+   - Exclude any variants with lifecycle = `REJECT` (a11y blocker)
+   - Check: scored variants loaded, REJECT variants excluded from ranking
+
+2. **Sort Within Each Category**
+   - For each category:
+     - Sort variants by `scores.total` descending
+     - Record rank position (1 = highest)
+   - Check: all categories sorted
+
+3. **Apply Tiebreaker Rule**
+   - For each pair of adjacent-ranked variants in a category:
+     - Calculate margin: `abs(score_a - score_b) / max(score_a, score_b) * 100`
+     - If margin <= 10%:
+       - Compare `scores.breadth`
+       - Higher breadth wins the higher rank
+       - Log: "Tiebreaker applied: {winner} (breadth={N}) beats {loser} (breadth={N}) within {margin}% margin"
+   - Authority: Nathan Curtis — network effect favors broader adoption
+   - Check: all ties resolved, tiebreaker applications logged
+
+4. **Identify Category Leaders**
+   - For each category:
+     - The rank-1 variant is the "category leader"
+     - If leader's `total_score >= 80` AND it's the highest in category → eligible for CANONICAL
+     - If leader's `total_score >= 60` → eligible for STABLE
+     - If leader's `total_score >= 40` → eligible for EXPERIMENTAL
+   - Check: category leaders identified with eligibility flags
+
+5. **Build Comparison Matrix**
+   - For each category with 2+ variants:
+     - Create head-to-head comparison showing which variant wins in each dimension
+     - Structure:
+       ```json
+       {
+         "category": "base",
+         "component": "button",
+         "variants": ["button-shared-v1", "button-clickmax-v2"],
+         "dimension_winners": {
+           "breadth": "button-shared-v1",
+           "quality": "button-clickmax-v2",
+           "consistency": "button-shared-v1",
+           "maturity": "button-shared-v1",
+           "simplicity": "button-clickmax-v2"
+         },
+         "overall_winner": "button-shared-v1",
+         "margin": "12%"
+       }
+       ```
+   - For categories with 1 variant: mark as "uncontested"
+   - Check: comparison matrix built for all multi-variant categories
+
+6. **Calculate Category Health**
+   - For each category:
+     - `avg_score`: average total score of all variants
+     - `max_score`: highest score
+     - `min_score`: lowest score
+     - `spread`: max - min
+     - `variant_count`: total variants
+     - `has_canonical`: boolean (any variant currently CANONICAL?)
+   - Categories with `avg_score < 40` flagged as "needs attention"
+   - Check: health metrics calculated for all categories
+
+7. **Generate Rankings Output**
+   - Create `rankings.json`:
+     ```json
+     {
+       "cycle": N,
+       "timestamp": "ISO-8601",
+       "categories": {
+         "base": {
+           "rankings": [...sorted variants with rank...],
+           "leader": { "id": "...", "score": N, "eligibility": "..." },
+           "comparisons": [...comparison matrices...],
+           "health": { "avg": N, "max": N, "min": N, "spread": N, "count": N }
+         },
+         ...
+       },
+       "tiebreakers_applied": [...],
+       "categories_needing_attention": [...]
+     }
+     ```
+   - Check: output valid JSON, all categories represented
+
+## Failure Handling
+
+- **Scored variants not found:** Abort with "Run ds-critical-eye-score first."
+- **Empty category:** Warn but continue (category present with 0 variants)
+- **All variants REJECTED in category:** Flag category as "blocked — all variants failed a11y"
+
+## Success Criteria
+
+- [ ] All variants ranked within their category
+- [ ] Tiebreaker rule applied where scores within 10%
+- [ ] Category leaders identified with eligibility flags
+- [ ] Comparison matrix built for multi-variant categories
+- [ ] Category health metrics calculated
+- [ ] Rankings JSON output complete and valid
+
+## Related Checklists
+
+- `squads/design/checklists/ds-critical-eye-review-checklist.md`