aiox-core 5.0.2 → 5.0.3

package/pro/squads/design/tasks/ds-govern-a11y-compliance.md

@@ -0,0 +1,93 @@
+# Task: ds-govern-a11y-compliance
+
+> Task ID: brad-ds-govern-a11y-compliance  
+> Agent: Brad Frost (Design System Architect)  
+> Purpose: Keep WCAG governance always current and release-blocking when stale or incomplete.
+
+## Overview
+
+This task operationalizes accessibility standards governance for the design system:
+
+1. Regenerate the canonical checklist from source text.
+2. Validate count/coverage/freshness constraints.
+3. Enforce release gate checklist.
+4. Produce auditable output for CI and handoff.
+5. Enforce AI-First governance protocol at task output level.
+
+## Preconditions
+
+- `docs/design-system/accessibility/manifest.json` exists.
+- `docs/design-system/accessibility/sources/wcag-22-criteria.pt-BR.md` exists.
+- Node.js available.
+- `squads/design/protocols/ai-first-governance.md` available.
+
+## Workflow
+
+### Step 1: Regenerate canonical checklist
+
+```bash
+npm run checklists:a11y:generate
+```
+
+Expected:
+- `squads/design/checklists/ds-accessibility-wcag-checklist.md` atualizado/sincronizado.
+- Counts: `87 total`, `86 active`, `1 removed`.
+
+### Step 2: Validate governance
+
+```bash
+npm run validate:a11y-checklists
+node squads/design/scripts/validate-a11y-integration.cjs
+```
+
+Validation must fail when:
+- IDs are missing/duplicated,
+- counts diverge,
+- manifest is stale,
+- integration artifacts are missing.
+
+### Step 3: Execute release gate checklist
+
+Checklist:
+- `squads/design/checklists/ds-a11y-release-gate-checklist.md`
+
+Mark gate as **APPROVED** only when all checks pass.
+
+### Step 4: Emit governance report
+
+Write a short report in:
+- `outputs/design-system/accessibility/governance-report.md`
+
+Include:
+- date/time
+- command outputs summary
+- pass/fail status
+- blocking reasons (if any)
+- explicit dependency status: `Implemented`, `Partially implemented`, `Concept only`
+- unresolved items and contradiction check result
+
+## Success Criteria
+
+- Canonical WCAG checklist regenerated and validated.
+- Release gate checklist fully checked.
+- CI can reproduce the same pass/fail result.
+- No manual criterion drift.
+
+## Output
+
+- `outputs/design-system/accessibility/governance-report.md`
+- Status do gate `APPROVED`/`BLOCKED` com evidências
+- Registro de execução dos checklists:
+  - `squads/design/checklists/ds-accessibility-wcag-checklist.md`
+  - `squads/design/checklists/ds-a11y-release-gate-checklist.md`
+
+## Related Checklists
+
+- `squads/design/checklists/ds-accessibility-wcag-checklist.md`
+- `squads/design/checklists/ds-a11y-release-gate-checklist.md`
+
+
+## Process Guards
+- **Execution Type:** `Hybrid`
+- **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `design-system`
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/ds-governance.md

@@ -0,0 +1,187 @@
+# Setup DS Governance Model
+
+> Task ID: brad-ds-governance
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+> **Execution Type:** `Hybrid`
+> **Human Checkpoint:** Review and approve the governance model, contribution flow, and decision-making process before implementation
+> **Dependencies:** depends_on: `[]` · enables: `[ds-designops]` · workflow: `governance`
+
+## Description
+
+Setup a governance model for your design system based on Nathan Curtis's team model frameworks. Defines contribution flow, decision-making process, versioning strategy, and communication channels.
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/governance/governance-model.md`
+- **format:** Markdown report
+- **consumed_by:** ds-designops
+
+## Prerequisites
+
+- Existing or planned design system
+- Understanding of team structure
+- Read data/ds-reference-architectures.md for governance patterns
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - Team size (DS team + consuming teams)
+   - Current DS maturity (new, growing, established)
+   - Decision-making style (centralized authority vs. consensus)
+   - Number of consuming products/teams
+
+2. **Model Recommendation**
+   Based on inputs, recommend one of:
+   - **Centralized:** Dedicated DS team builds and maintains everything. Best for: small org, new DS, need consistency.
+   - **Federated:** Product teams contribute components. Best for: large org, mature DS, diverse needs.
+   - **Hybrid:** Central team + product contributions with review. Best for: mid-size org, growing DS.
+
+### Steps
+
+1. **Define Governance Model**
+   - Select model based on elicitation
+   - Define DS team responsibilities
+   - Define consuming team responsibilities
+   - Define escalation path for disagreements
+   - Check: selected model's team_size range includes user's team_size AND maturity level matches
+
+2. **Create Contribution Flow**
+   - Propose: How teams request new components or changes
+   - Review: Who reviews contributions and with what criteria
+   - Approve: Decision authority and timeline expectations
+   - Release: How approved changes get into the DS
+   - Document the flow with clear steps and owners
+   - Check: contribution flow has exactly 4+ named stages with owner and SLA per stage
+
+3. **Define Decision Log Template**
+   - What was decided
+   - Why (rationale with alternatives considered)
+   - Who decided
+   - When it can be revisited
+   - Impact on existing consumers
+   - Check: decision log template has >= 5 fields: what, why, who, when, impact
+
+4. **Setup Communication Channels**
+   - Announcements: Major releases, breaking changes
+   - Support: Questions, bug reports, feature requests
+   - Contribution: PRs, reviews, discussions
+   - Recommendations per platform (Slack channels, GitHub discussions, etc.)
+   - Check: each channel has: platform, purpose (1 sentence), audience (team list), and notification rules
+
+5. **Define Versioning Strategy**
+   - Semantic versioning rules (major/minor/patch)
+   - Breaking change policy (deprecation period, migration guides)
+   - Release cadence (fixed schedule vs. continuous)
+   - Changelog requirements
+   - Check: versioning strategy defines: semver rules, breaking change deprecation period (in sprints), and changelog format
+
+6. **Generate Governance Documentation**
+   - governance-model.md — Model description and rationale
+   - contribution-guide.md — How to contribute to the DS
+   - decision-log-template.md — Template for recording decisions
+   - Update .state.yaml
+
+## Examples
+
+### Example 1: Centralized Model (Startup, 30 people)
+
+**Input:** `*ds-govern` with team_size=30, maturity=new, style=centralized, products=2
+
+**Output (governance-model.md excerpt):**
+```
+# Design System Governance — Acme Corp
+
+## Model: Centralized
+
+### DS Team (3 people)
+- 1 DS Lead (owns roadmap, reviews all contributions)
+- 1 DS Engineer (builds components, maintains tokens)
+- 1 DS Designer (Figma library, documentation)
+
+### Decision Authority
+| Decision Type | Who Decides | SLA |
+|--------------|-------------|-----|
+| New component | DS Lead | 5 business days |
+| Token change | DS Engineer + DS Designer | 3 business days |
+| Breaking change | DS Lead + Engineering Manager | 10 business days |
+| Bug fix | Any DS team member | 1 business day |
+
+### Contribution Flow
+1. Consumer team opens GitHub Issue with component request
+2. DS Designer reviews design feasibility (2 days)
+3. DS Lead approves/rejects with rationale (3 days)
+4. If approved: DS Engineer implements, DS Designer reviews
+5. Release in next scheduled version (bi-weekly)
+```
+
+### Example 2: Federated Model (Enterprise, 200+ people)
+
+**Input:** `*ds-govern` with team_size=200, maturity=established, style=federated, products=8
+
+**Output (contribution-guide.md excerpt):**
+```
+# Contributing to the Design System
+
+## Who Can Contribute
+Any product team can propose components. The DS Core Team reviews all PRs.
+
+## Contribution Checklist
+- [ ] Component follows Atomic Design naming (atoms/molecules/organisms)
+- [ ] All styling uses design tokens (zero hardcoded values)
+- [ ] Unit tests with >80% coverage
+- [ ] Storybook stories for all variants
+- [ ] WCAG AA accessibility verified
+- [ ] TypeScript strict mode, no `any` types
+- [ ] Documentation in component README
+
+## Review Process
+1. **Draft PR** — contributor opens PR with component + tests + stories
+2. **Automated checks** — CI runs lint, typecheck, tests, visual regression
+3. **DS Core review** — 2 reviewers from Core Team (SLA: 5 business days)
+4. **Design review** — DS Designer verifies Figma alignment (SLA: 3 business days)
+5. **Merge** — Squash merge to main, auto-publish to npm
+6. **Announce** — Changelog entry + Slack #design-system notification
+```
+
+## Anti-Patterns
+
+- **"Governance by committee"** — Having >5 approvers for every change. Creates bottlenecks and frustration. Fix: Define clear ownership per component area
+- **"Phantom governance"** — Writing governance docs that nobody follows. Fix: Automate enforcement via CI checks and PR templates
+- **"One-size-fits-all"** — Applying enterprise governance to a 10-person startup (or vice versa). Fix: Match governance complexity to org size
+- **"No deprecation policy"** — Removing components without warning. Fix: Minimum 2-sprint deprecation window with migration guide
+- **"Silent changes"** — Pushing breaking changes without announcement. Fix: Mandatory changelog entry + Slack notification for every release
+
+## Output
+
+- `governance-model.md` — Governance model documentation
+- `contribution-guide.md` — Contribution workflow guide
+- `decision-log-template.md` — Decision log template
+- `.state.yaml` updated
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+- `squads/design/checklists/ds-migration-readiness-checklist.md`
+
+## Failure Handling
+
+- **Team size or maturity level doesn't match any standard model:** Create custom hybrid model combining elements from centralized and federated, document rationale for deviation from reference architectures
+- **No consensus on decision authority mapping:** Document competing viewpoints in decision log, escalate to stakeholder vote, implement temporary interim model with 30-day review checkpoint
+- **Communication channels unavailable (no Slack/GitHub):** Substitute with available platforms (email lists, Teams, Jira), maintain same channel purposes with adapted notification rules
+- **Contribution flow SLAs rejected as unrealistic:** Negotiate revised timelines with stakeholders, document capacity constraints, phase implementation with lighter-weight initial version
+
+## Success Criteria
+
+- [ ] Governance model document generated (governance-model.md) with decision authority table
+- [ ] Contribution flow defined with specific SLAs per decision type (in business days)
+- [ ] Decision log template has minimum 5 fields (what, why, who, when, impact)
+- [ ] Communication channels defined with platform and audience for each
+- [ ] Versioning strategy includes breaking change policy with deprecation period
+- [ ] All generated documentation is actionable (contains tables, checklists, or templates — not just prose)
+
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/ds-health-metrics.md

@@ -0,0 +1,278 @@
+# Task: Design System Health Metrics
+
+> Command: `*ds-health [path]`
+> Purpose: Generate comprehensive health dashboard for the design system
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[bundle-audit, token-usage-analytics, dead-code-detection]` · workflow: `metrics`
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/metrics/health-report.json`
+- **format:** JSON data
+- **consumed_by:** bundle-audit, token-usage-analytics, dead-code-detection
+
+## Overview
+
+This task runs grep-based scans across the entire design system and generates a health report with:
+- Token coverage metrics
+- Component adoption rates
+- Bundle size analysis
+- Code quality indicators
+- Consistency scores
+
+## Prerequisites
+
+- Design tokens spec: `squads/super-agentes/data/design-tokens-spec.yaml`
+- Target path (default: `app/components/`)
+
+## Execution Steps
+
+### Step 1: Token Coverage Analysis
+
+Run grep to count token-based styles vs hardcoded values in all component files.
+
+```bash
+# Count total style declarations
+total_styles=$(grep -rn --include="*.tsx" "className=" {path}/ | wc -l)
+
+# Count token-based styles (using CSS vars or Tailwind tokens)
+token_styles=$(grep -rn --include="*.tsx" \
+  "studio-\|var(--\|text-foreground\|bg-background\|border-border" {path}/ | wc -l)
+
+# Count hardcoded styles
+hardcoded=$(grep -rn --include="*.tsx" "#[0-9A-Fa-f]\{6\}" {path}/ | wc -l)
+```
+
+**Metrics:**
+- Token Coverage: `(token_styles / total_styles) * 100`
+- Hardcoded Violations: count of hex colors
+- Target: >95% token coverage
+
+### Step 2: Component Adoption Analysis
+
+Track which design system components are being used.
+
+```bash
+# Count imports of UI components
+grep -rn --include="*.tsx" "from '@/components/ui" {path}/ \
+  | sed 's/.*\/ui\/\([^'"'"']*\).*/\1/' \
+  | sort | uniq -c | sort -rn
+```
+
+**Output:**
+```
+  47 button
+  32 card
+  28 input
+  15 dialog
+  12 badge
+   8 tooltip
+   3 avatar
+   0 slider (unused)
+```
+
+**Metrics:**
+- Total UI Components: count
+- Components in Use: count with >0 imports
+- Adoption Rate: `(used / total) * 100`
+- Unused Components: list
+
+### Step 3: Bundle Size Analysis
+
+Calculate CSS and JS size per component.
+
+```bash
+# Estimate CSS class usage (Tailwind purge analysis)
+grep -rohn --include="*.tsx" 'className="[^"]*"' {path}/ \
+  | tr ' ' '\n' \
+  | sort | uniq -c | sort -rn \
+  | head -50
+
+# Count unique Tailwind classes
+unique_classes=$(grep -rohn --include="*.tsx" 'className="[^"]*"' {path}/ \
+  | tr ' ' '\n' | tr '"' '\n' | grep -v "^$" \
+  | sort -u | wc -l)
+```
+
+**Metrics:**
+- Unique CSS Classes: count
+- Estimated CSS Size: `unique_classes * 50 bytes` (rough estimate)
+- Bundle Target: <50KB CSS
+
+### Step 4: Code Quality Indicators
+
+```bash
+# Lines per component (complexity indicator)
+find {path}/ -name "*.tsx" -exec wc -l {} \; | sort -rn | head -20
+
+# Components over 200 lines (candidates for refactoring)
+over_200=$(find {path}/ -name "*.tsx" -exec wc -l {} \; \
+  | awk '$1 > 200 {print}' | wc -l)
+
+# TypeScript strict compliance
+tsc_errors=$(npx tsc --noEmit 2>&1 | grep "error TS" | wc -l)
+```
+
+**Metrics:**
+- Avg Lines per Component: average
+- Components >200 lines: count (should be 0)
+- TypeScript Errors: count (should be 0)
+
+### Step 5: Consistency Score
+
+Check for pattern consistency across codebase.
+
+```bash
+# Naming convention compliance
+# Components should be PascalCase
+non_pascal=$(find {path}/ -name "*.tsx" \
+  | xargs basename -a | grep -v "^[A-Z]" | wc -l)
+
+# Import style consistency
+# Should use @/ aliases
+relative_imports=$(grep -rn "from '\.\./\.\./\.\." {path}/ | wc -l)
+
+# Barrel export compliance
+missing_barrels=$(find {path}/ -type d -mindepth 1 \
+  | while read dir; do
+      [ ! -f "$dir/index.ts" ] && echo "$dir"
+    done | wc -l)
+```
+
+**Metrics:**
+- Naming Compliance: `(pascal / total) * 100`
+- Import Consistency: `(1 - relative/total) * 100`
+- Barrel Coverage: `(with_barrel / total_dirs) * 100`
+
+### Step 6: Generate Health Report
+
+**Output Format:**
+
+```markdown
+# Design System Health Report
+Generated: {timestamp}
+Path: {path}
+
+## Overall Health Score: {score}/100
+
+### Token Coverage
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| Token Usage | 94.2% | >95% | ⚠️ |
+| Hardcoded Colors | 12 | 0 | ❌ |
+| CSS Variables | 847 | - | ✅ |
+
+### Component Adoption
+| Metric | Value | Status |
+|--------|-------|--------|
+| Total Components | 45 | - |
+| Components in Use | 38 | 84% |
+| Unused Components | 7 | ⚠️ |
+
+**Unused:** slider, menubar, navigation-menu, ...
+
+### Bundle Analysis
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| Unique CSS Classes | 234 | <500 | ✅ |
+| Est. CSS Size | 12KB | <50KB | ✅ |
+| Largest Component | Card (8KB) | - | - |
+
+### Code Quality
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| Avg Lines/Component | 87 | <200 | ✅ |
+| Components >200 lines | 3 | 0 | ⚠️ |
+| TypeScript Errors | 0 | 0 | ✅ |
+
+**Over 200 lines:** FeedbackSection (373), ListGroupsView (289), ...
+
+### Consistency
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| Naming Compliance | 98% | 100% | ⚠️ |
+| Import Consistency | 100% | 100% | ✅ |
+| Barrel Coverage | 95% | 100% | ⚠️ |
+
+## Recommendations
+
+1. **HIGH:** Fix 12 hardcoded colors in Button.tsx, Card.tsx
+2. **MEDIUM:** Refactor 3 components over 200 lines
+3. **LOW:** Add barrel exports to 2 directories
+4. **INFO:** Consider removing 7 unused UI components
+
+## Trend (if previous report exists)
+| Metric | Previous | Current | Change |
+|--------|----------|---------|--------|
+| Health Score | 78 | 85 | +7 ↑ |
+| Token Coverage | 91% | 94% | +3% ↑ |
+| Components >200 | 8 | 3 | -5 ↓ |
+```
+
+## Health Score Calculation
+
+```yaml
+health_score:
+  weights:
+    token_coverage: 30      # 0-30 points
+    component_adoption: 15  # 0-15 points
+    bundle_size: 15         # 0-15 points
+    code_quality: 25        # 0-25 points
+    consistency: 15         # 0-15 points
+
+  scoring:
+    token_coverage:
+      100%: 30
+      95%: 27
+      90%: 24
+      <90%: (coverage * 0.3)
+
+    code_quality:
+      0_errors_0_over200: 25
+      0_errors_some_over200: 20
+      some_errors: 10
+      many_errors: 0
+```
+
+## Output Location
+
+```
+outputs/design-system/{project}/
+├── health-report-{date}.md
+├── health-history.json
+└── metrics/
+    ├── token-coverage.json
+    ├── component-adoption.json
+    ├── bundle-analysis.json
+    └── code-quality.json
+```
+
+## Failure Handling
+
+- **Token spec file not found:** Skip token coverage step, calculate remaining metrics, note "token coverage: N/A — spec file missing" in report
+- **No component files in path:** Exit with error "No .tsx files found in {path}. Verify design system path."
+- **TypeScript compiler not available:** Skip tsc_errors metric, log "TypeScript check skipped — tsc not found" in report
+- **Grep returns zero matches for all token patterns:** Verify grep patterns match project's token format (CSS vars, Tailwind, styled-components). Adjust patterns and retry once
+
+## Success Criteria
+
+- [ ] Health score calculated (0-100)
+- [ ] All metrics collected
+- [ ] Report generated in markdown
+- [ ] Recommendations prioritized
+- [ ] Historical comparison (if previous exists)
+
+## Related Commands
+
+- `*validate-tokens` - Deep dive on token violations
+- `*bundle-audit` - Detailed bundle analysis
+- `*token-usage` - Token usage analytics
+- `*dead-code` - Unused code detection
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/ds-integrate-squad.md

@@ -0,0 +1,130 @@
+# Integrate with Squad
+
+> Task ID: atlas-integrate-squad
+> Agent: Merovingian (Design System Builder)
+> Version: 1.0.0
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `integration`
+
+## Description
+
+Connect design system with MMOS, CreatorOS, or InnerLens expansion packs. Generates pack-specific patterns, token variations, and integration documentation.
+
+## Prerequisites
+
+- Design system setup complete
+- Components built
+- Target expansion pack installed
+
+## Workflow
+
+### Steps
+
+1. **Detect Target Pack** - Identify MMOS, CreatorOS, or InnerLens
+2. **Load Pack Requirements** - Read pack-specific pattern needs
+3. **Generate Token Variations** - Personality/theme-based tokens
+4. **Generate Pack-Specific Patterns** - Custom components for pack
+5. **Create Integration Hooks** - Connect pack workflows
+6. **Generate Integration Docs** - Usage guide for pack
+7. **Test Integration** - Validate pack can use patterns
+8. **Update State** - Track integration completion
+
+## Output
+
+- Pack-specific components
+- Token variations
+- Integration documentation
+- Example usage
+
+## Failure Handling
+
+- **Target pack not found in expected location:** If MMOS/CreatorOS/InnerLens directory does not exist at standard paths, prompt user for custom pack location or exit with "Pack not found — verify pack is installed and provide path"
+- **Pack-specific token variations conflict with base tokens:** If personality/theme tokens (e.g., MMOS formal mode) override base system tokens causing visual inconsistency, namespace the pack tokens (e.g., mmos-formal-*) and document in integration guide
+- **Pack imports fail due to missing dependencies:** If pack requires DS components not yet built (e.g., CreatorOS needs VideoPlayer but DS has no media components), generate placeholder component stubs and note "Stubs created for: {list} — implement full components before production"
+- **Integration test suite fails in pack context:** If DS components render incorrectly or error when imported by pack (e.g., missing context provider, broken prop types), isolate failing components, document integration requirements, and suggest pack-specific wrapper pattern
+
+## Success Criteria
+
+- [ ] Pack can import and use design system
+- [ ] Token variations work correctly
+- [ ] Pack-specific patterns functional
+- [ ] Integration documented
+- [ ] No regressions in pack functionality
+
+## Examples
+
+### MMOS Integration
+
+```typescript
+// Personality token variations
+{
+  formal: {
+    fontFamily: 'var(--font-serif)',
+    spacing: 'var(--space-formal)',
+    colorPrimary: 'var(--color-corporate)'
+  },
+  casual: {
+    fontFamily: 'var(--font-sans)',
+    spacing: 'var(--space-relaxed)',
+    colorPrimary: 'var(--color-friendly)'
+  }
+}
+
+// CloneChatInterface component
+<CloneChatInterface
+  personality="formal"
+  tokens={personalityTokens.formal}
+/>
+```
+
+### CreatorOS Integration
+
+```typescript
+// Educational token variations
+{
+  fonts: 'readable (18px)',
+  lineHeight: '1.6 (comprehension)',
+  spacing: 'generous',
+  colors: 'highlight focus'
+}
+
+// CourseVideoPlayer component
+<CourseVideoPlayer
+  tokens={educationalTokens}
+  accessibility="WCAG AAA"
+/>
+```
+
+### InnerLens Integration
+
+```typescript
+// Minimal distraction tokens
+{
+  colors: 'neutral, minimal',
+  layout: 'clean, focused',
+  spacing: 'balanced'
+}
+
+// AssessmentForm component
+<AssessmentForm
+  tokens={minimalTokens}
+  validationUI={systemValidation}
+/>
+```
+
+## Notes
+
+- Each pack has unique requirements
+- Token variations maintain consistency
+- Pack-specific components extend base system
+- Integration is bidirectional (pack ↔ design system)
+- Document in pack's README
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.