aiox-core 5.0.2 → 5.0.4

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

@@ -0,0 +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.

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

@@ -0,0 +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`

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

@@ -0,0 +1,139 @@
+# Critical Eye — Make Lifecycle Transition Decisions
+
+> Task ID: ds-critical-eye-decide
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[ds-critical-eye-compare]` · enables: `[ds-critical-eye-report]` · workflow: `critical-eye`
+
+## Description
+
+Apply lifecycle transition rules to all ranked variants. Auto-transitions execute immediately: CANDIDATE→EXPERIMENTAL (breadth >= 10), EXPERIMENTAL→STABLE (total >= 60). Checkpoint transitions generate proposals for human review: STABLE→CANONICAL (total >= 80 + highest in category), CANONICAL→DEPRECATED (superseded by 10+ margin). The absolute blocker (a11y = 0 → REJECT) was already applied in the score step.
+
+All decisions are logged to the append-only `canonical-decisions.json` for full traceability.
+
+## Output Schema
+- **produces:**
+  - `outputs/design-system/critical-eye/cycle-{N}/decisions.json` — executed auto-transitions
+  - `outputs/design-system/critical-eye/cycle-{N}/proposals.json` — checkpoint proposals for design-chief
+  - Updates `workspace/ui/pattern-catalog.json` — lifecycle + scores
+  - Appends to `workspace/ui/canonical-decisions.json` — decision log
+- **consumed_by:** ds-critical-eye-report, ds-critical-eye-review-checklist (for proposals)
+
+## Prerequisites
+
+- Rankings output from `ds-critical-eye-compare` available
+- `pattern-catalog.json` writable
+- `canonical-decisions.json` writable
+- `critical-eye-scoring-rules.yaml` loaded (for transition rules)
+
+## Workflow
+
+### Steps
+
+1. **Load Inputs**
+   - Read `rankings.json` from previous step
+   - Read `pattern-catalog.json` (will be updated)
+   - Read `canonical-decisions.json` (will be appended)
+   - Read `critical-eye-scoring-rules.yaml` → `lifecycle.transitions` section
+   - Check: all files loaded and valid
+
+2. **Evaluate Auto-Transitions**
+   - For each variant, check current lifecycle and scores:
+   - **CANDIDATE → EXPERIMENTAL** (auto):
+     - Condition: `breadth_score >= 10` (appears in 2+ sources)
+     - If met: execute transition immediately
+   - **EXPERIMENTAL → STABLE** (auto):
+     - Condition: `total_score >= 60`
+     - If met: execute transition immediately
+   - **ANY → REJECT** (auto, blocker):
+     - Condition: `accessibility_score == 0`
+     - Already handled in score step, but verify no regressions
+   - Check: all auto-transitions evaluated
+
+3. **Execute Auto-Transitions**
+   - For each auto-transition:
+     - Update `variant.lifecycle` in pattern-catalog.json
+     - Append to `variant.lifecycleHistory`:
+       ```json
+       {
+         "from": "CANDIDATE",
+         "to": "EXPERIMENTAL",
+         "cycle": N,
+         "type": "auto",
+         "reason": "breadth_score >= 10 (2 sources)",
+         "timestamp": "ISO-8601"
+       }
+       ```
+     - Create decision entry for `canonical-decisions.json`
+   - Check: all auto-transitions applied and logged
+
+4. **Generate Checkpoint Proposals**
+   - **STABLE → CANONICAL** (requires design-chief approval):
+     - Condition: `total_score >= 80 AND highest_in_category`
+     - If met: create proposal (NOT executed yet)
+     - Include: variant ID, scores, category leader status, comparison matrix
+   - **CANONICAL → DEPRECATED** (requires design-chief approval):
+     - Condition: `new_canonical_candidate_score > current_canonical_score + 10`
+     - If met: create deprecation proposal with replacement candidate
+   - Check: all proposals generated with full justification
+
+5. **Update Pattern Catalog**
+   - Write updated scores for ALL variants (even those with no transition)
+   - Update `evaluationCycle` to current cycle number
+   - Update `lastEvaluatedAt` to current timestamp
+   - For each variant: update `lastScoredAtCycle` to current cycle
+   - Check: catalog saved with no data loss, cycle number incremented
+
+6. **Append to Decisions Log**
+   - For each decision (auto-transition executed):
+     ```json
+     {
+       "id": "decision-{cycle}-{index}",
+       "cycle": N,
+       "timestamp": "ISO-8601",
+       "variantId": "button-shared-v1",
+       "category": "base",
+       "transition": { "from": "CANDIDATE", "to": "EXPERIMENTAL" },
+       "type": "auto",
+       "scores": { "total": 65, "breadth": 10, "quality": 22, ... },
+       "reason": "breadth_score >= 10 (2 sources detected)",
+       "authority": "Nathan Curtis / EightShapes — Usage Breadth Scale",
+       "previousDecision": null
+     }
+     ```
+   - Update `canonical-decisions.json.lastCycle` to current cycle
+   - Check: decisions appended (not overwritten), log integrity preserved
+
+7. **Generate Decision Outputs**
+   - `decisions.json`: all auto-transitions executed this cycle
+   - `proposals.json`: all checkpoint proposals awaiting human review
+   - Check: both files valid JSON
+
+## Failure Handling
+
+- **Rankings not found:** Abort with "Run ds-critical-eye-compare first."
+- **Catalog write failure:** CRITICAL — abort immediately, do not corrupt catalog
+- **Decisions log write failure:** Log to console, create backup decisions file
+- **Conflicting transitions:** If a variant qualifies for multiple transitions, apply the highest-priority one (REJECT > any other)
+
+## Success Criteria
+
+- [ ] All auto-transitions (CANDIDATE→EXPERIMENTAL, EXPERIMENTAL→STABLE) executed
+- [ ] Checkpoint proposals (STABLE→CANONICAL, CANONICAL→DEPRECATED) generated
+- [ ] Pattern catalog updated with new scores and lifecycle states
+- [ ] Decisions log appended with full traceability
+- [ ] No data corruption in catalog or decisions log
+- [ ] Cycle number incremented
+- [ ] Every decision cites authority source from scoring rules
+
+## Anti-Patterns
+
+- **"Silent transition"** — Executing a transition without logging it. Every transition MUST be in the decisions log.
+- **"Forced canonical"** — Promoting to CANONICAL without the design-chief checkpoint. Auto-transitions STOP at STABLE.
+- **"Retroactive scoring"** — Changing scores after decisions are made. Scores are immutable once logged. Re-score in next cycle.
+
+## Related Checklists
+
+- `squads/design/checklists/ds-critical-eye-review-checklist.md`

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

@@ -0,0 +1,111 @@
+# Critical Eye — Inventory Variants Per Category
+
+> Task ID: ds-critical-eye-inventory
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[ds-critical-eye-score]` · workflow: `critical-eye`
+
+## Description
+
+Scan `pattern-catalog.json` and group all variants by category. Detect new variants added since the last cycle (from latest Figma extraction or manual registration). Cross-reference with `registry.json`, component metadata, and brand files to ensure completeness.
+
+This is Step 1 of the Critical Eye workflow — the foundation that all subsequent scoring depends on.
+
+## Output Schema
+- **produces:** `outputs/design-system/critical-eye/cycle-{N}/inventory.json`
+- **format:** JSON — variants grouped by category with source cross-references
+- **consumed_by:** ds-critical-eye-score
+
+## Prerequisites
+
+- `workspace/ui/pattern-catalog.json` exists and contains at least 1 variant
+- `squads/design/data/critical-eye-scoring-rules.yaml` loaded (for category definitions)
+- `workspace/ui/registry.json` accessible (for cross-reference)
+- `workspace/domains/design-system/metadata/components.json` accessible
+
+## Workflow
+
+### Steps
+
+1. **Load Catalog and Rules**
+   - Read `pattern-catalog.json`
+   - Read `critical-eye-scoring-rules.yaml` → extract `categories` section
+   - Determine cycle number: `catalog.evaluationCycle + 1`
+   - Check: catalog file exists AND is valid JSON AND has `variants` array
+
+2. **Group Variants by Category**
+   - For each variant in `catalog.variants`:
+     - Map to the category defined in `scoring-rules.categories` (base, core, layout, navigation, feedback, data)
+     - If variant.category not found in rules, flag as `UNCATEGORIZED`
+   - Check: every variant mapped to exactly one category OR flagged
+
+3. **Detect New Variants**
+   - Compare each variant's `addedAtCycle` with current cycle number
+   - Variants where `addedAtCycle == currentCycle` OR `lastScoredAtCycle == null` are flagged as `NEW`
+   - Check: new variant count logged
+
+4. **Cross-Reference with Registry**
+   - For each variant with a `metadata.registryKey`:
+     - Verify the key exists in `registry.json.items[]`
+     - Verify the component files listed in metadata actually exist on disk
+   - Flag variants with broken references as `ORPHANED`
+   - Check: zero ORPHANED variants (warn if any)
+
+5. **Cross-Reference with Component Metadata**
+   - For each variant with a `metadata.componentMetadata` path:
+     - Verify the metadata JSON exists
+     - Extract: variants count, states count, a11y coverage
+   - Enrich inventory with these details for scoring step
+   - Check: metadata enrichment successful for all non-null paths
+
+6. **Count Sources Per Variant**
+   - For each variant, count `variant.sources.length`
+   - This feeds directly into the breadth dimension of scoring
+   - Check: source counts populated for all variants
+
+7. **Generate Inventory Output**
+   - Create `inventory.json` with structure:
+     ```json
+     {
+       "cycle": N,
+       "timestamp": "ISO-8601",
+       "totalVariants": count,
+       "newVariants": count,
+       "orphanedVariants": count,
+       "categories": {
+         "base": { "variants": [...], "count": N },
+         "core": { "variants": [...], "count": N },
+         ...
+       }
+     }
+     ```
+   - Check: output JSON is valid AND all categories represented
+
+## Failure Handling
+
+- **Catalog not found:** Abort with "pattern-catalog.json not found. Run Wave 1 foundation first."
+- **Invalid JSON:** Abort with parsing error details
+- **Orphaned variants:** Warn but continue (non-blocking). Log orphaned IDs in output.
+- **Empty catalog:** Abort with "No variants to inventory. Add components to pattern-catalog.json first."
+
+## Success Criteria
+
+- [ ] All variants in catalog grouped by category
+- [ ] New variants (since last cycle) identified
+- [ ] Cross-reference with registry.json completed
+- [ ] Cross-reference with component metadata completed
+- [ ] Source counts populated for breadth scoring
+- [ ] Inventory JSON output is valid and complete
+- [ ] Zero uncategorized variants (or explicitly flagged)
+
+## Error Handling
+
+- **Missing files**: Report which reference file is missing, suggest corrective action
+- **Category mismatch**: If variant.category not in scoring rules, list valid categories
+- **Stale data**: If component metadata newer than catalog entry, flag for re-sync
+
+## Related Checklists
+
+- `squads/design/checklists/ds-critical-eye-review-checklist.md`

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

@@ -0,0 +1,101 @@
+# Critical Eye — Generate Cycle Report
+
+> Task ID: ds-critical-eye-report
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[ds-critical-eye-decide]` · enables: `[]` · workflow: `critical-eye`
+
+## Description
+
+Compile a comprehensive cycle report summarizing everything that happened in this Critical Eye evaluation cycle. Includes: summary statistics, all scores by category, transitions executed, proposals pending, category health overview, and recommendations for next cycle.
+
+Uses the `critical-eye-cycle-report-tmpl.md` template for consistent formatting across cycles.
+
+## Output Schema
+- **produces:** `outputs/design-system/critical-eye/cycle-{N}/report.md`
+- **format:** Markdown — human-readable report following template
+- **consumed_by:** design-chief (review), team (visibility)
+
+## Prerequisites
+
+- All previous Critical Eye steps completed (inventory, score, compare, decide)
+- Template: `squads/design/templates/critical-eye-cycle-report-tmpl.md`
+
+## Workflow
+
+### Steps
+
+1. **Load All Cycle Data**
+   - Read `inventory.json` — variant counts, new variants, orphans
+   - Read `scored.json` — all scores by variant
+   - Read `rankings.json` — rankings, leaders, comparisons, health
+   - Read `decisions.json` — auto-transitions executed
+   - Read `proposals.json` — pending checkpoint proposals
+   - Read `review-decisions.json` (if exists) — design-chief review results
+   - Check: all required files loaded
+
+2. **Calculate Summary Statistics**
+   - Total variants evaluated
+   - New variants this cycle
+   - Transitions executed: count by type (CANDIDATE→EXPERIMENTAL, EXPERIMENTAL→STABLE, REJECT)
+   - Proposals pending human review
+   - Average score across all variants
+   - Highest score / lowest score (non-REJECT)
+   - Categories evaluated
+   - Categories needing attention (avg < 40)
+   - Check: statistics calculated
+
+3. **Build Category Breakdown**
+   - For each category:
+     - Leader variant + score
+     - All variants with scores (table format)
+     - Transitions that occurred
+     - Health metrics (avg, spread, count)
+     - Recommendation (e.g., "needs more sources", "ready for canonical review", "healthy")
+   - Check: all categories represented
+
+4. **Build Transition Summary**
+   - Table of all transitions executed:
+     | Variant | From | To | Score | Reason |
+   - Separate section for proposals awaiting review:
+     | Variant | Proposed | Score | Requires |
+   - Check: all transitions and proposals listed
+
+5. **Generate Recommendations**
+   - **Immediate actions:** Variants close to thresholds (e.g., score 78 — almost CANONICAL)
+   - **Source gaps:** Variants with breadth = 0 (snowflake) — recommend finding additional sources
+   - **Quality gaps:** Variants with low quality sub-scores — recommend specific improvements
+   - **A11y concerns:** Variants with low (but non-zero) accessibility — recommend remediation
+   - **Next cycle focus:** Categories with most room for improvement
+   - Check: at least 1 recommendation generated
+
+6. **Render Report Using Template**
+   - Load `critical-eye-cycle-report-tmpl.md`
+   - Fill in all sections with computed data
+   - Include timestamp, cycle number, scoring rules version
+   - Check: template sections all populated
+
+7. **Save Report**
+   - Write to `outputs/design-system/critical-eye/cycle-{N}/report.md`
+   - Check: file saved successfully
+
+## Failure Handling
+
+- **Missing cycle data:** Generate partial report with available data, note gaps
+- **Template not found:** Use inline format (degrade gracefully)
+- **No transitions this cycle:** Note "No lifecycle changes this cycle" — not an error
+
+## Success Criteria
+
+- [ ] Report includes summary statistics
+- [ ] All categories covered with scores and rankings
+- [ ] Transition summary complete (executed + proposals)
+- [ ] Recommendations generated for next cycle
+- [ ] Template format followed
+- [ ] Report saved to correct cycle output directory
+
+## Related Checklists
+
+- `squads/design/checklists/ds-critical-eye-review-checklist.md`