aios-core 2.1.0

package/.aios-core/development/tasks/audit-utilities.md

@@ -0,0 +1,358 @@
+---
+
+# audit-utilities
+
+## 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: auditUtilities()
+responsável: Quinn (Guardian)
+responsavel_type: Agente
+atomic_layer: Strategy
+
+**Entrada:**
+- campo: target
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid path or identifier
+
+- campo: options
+  tipo: object
+  origem: config
+  obrigatório: false
+  validação: Analysis configuration
+
+- campo: depth
+  tipo: number
+  origem: User Input
+  obrigatório: false
+  validação: Default: 1 (0-3)
+
+**Saída:**
+- campo: analysis_report
+  tipo: object
+  destino: File (.ai/*.json)
+  persistido: true
+
+- campo: findings
+  tipo: array
+  destino: Memory
+  persistido: false
+
+- campo: metrics
+  tipo: object
+  destino: Memory
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target exists and is accessible; analysis tools available
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target exists and is accessible; analysis tools available
+    error_message: "Pre-condition failed: Target exists and is accessible; analysis tools available"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Analysis complete; report generated; no critical issues
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify analysis complete; report generated; no critical issues
+    error_message: "Post-condition failed: Analysis complete; report generated; no critical issues"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Analysis accurate; all targets covered; report complete
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert analysis accurate; all targets covered; report complete
+    error_message: "Acceptance criterion not met: Analysis accurate; all targets covered; report complete"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** code-analyzer
+  - **Purpose:** Static code analysis and metrics
+  - **Source:** .aios-core/utils/code-analyzer.js
+
+- **Tool:** file-system
+  - **Purpose:** Recursive directory traversal
+  - **Source:** Node.js fs module
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** analyze-codebase.js
+  - **Purpose:** Codebase analysis and reporting
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/analyze-codebase.js
+
+---
+
+## Error Handling
+
+**Strategy:** fallback
+
+**Common Errors:**
+
+1. **Error:** Target Not Accessible
+   - **Cause:** Path does not exist or permissions denied
+   - **Resolution:** Verify path and check permissions
+   - **Recovery:** Skip inaccessible paths, continue with accessible ones
+
+2. **Error:** Analysis Timeout
+   - **Cause:** Analysis exceeds time limit for large codebases
+   - **Resolution:** Reduce analysis depth or scope
+   - **Recovery:** Return partial results with timeout warning
+
+3. **Error:** Memory Limit Exceeded
+   - **Cause:** Large codebase exceeds memory allocation
+   - **Resolution:** Process in batches or increase memory limit
+   - **Recovery:** Graceful degradation to summary analysis
+
+---
+
+## 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
+```
+
+---
+
+## Configuration Dependencies
+
+This task requires the following configuration keys from `core-config.yaml`:
+
+- **`devStoryLocation`**: Location of story files (typically docs/stories)
+
+- **`qaLocation`**: QA output directory (typically docs/qa) - Required to write quality reports and gate files
+
+**Loading Config:**
+```javascript
+const yaml = require('js-yaml');
+const fs = require('fs');
+const path = require('path');
+
+const configPath = path.join(__dirname, '../../.aios-core/core-config.yaml');
+const config = yaml.load(fs.readFileSync(configPath, 'utf8'));
+
+const dev_story_location = config.devStoryLocation;
+const qaLocation = config.qaLocation || 'docs/qa'; // qaLocation
+```
+
+## Purpose
+
+Systematically audit all utilities in `.aios-core/scripts/` to determine their functional status, classify them as WORKING/FIXABLE/DEPRECATED, and generate actionable recommendations for maintenance and cleanup.
+
+## Classification Criteria
+
+### ✅ WORKING
+- Executes without errors
+- Dependencies installed
+- Integrated with at least one agent/task
+- Documentation exists (inline or external)
+
+### 🔧 FIXABLE
+- Executes with minor errors (missing deps, syntax fixes)
+- Core logic sound, needs integration
+- Fix effort estimated <4 hours
+- Concept valuable enough to justify fix
+
+### 🗑️ DEPRECATED
+- Non-functional, major rewrites needed
+- Obsolete concept (replaced by better approach)
+- Fix effort >8 hours
+- Low value relative to effort
+
+## Execution Steps
+
+### Step 1: Run Automated Testing
+
+Execute the test-utilities.js script to test all utilities:
+
+```bash
+node .aios-core/scripts/test-utilities.js
+```
+
+This will:
+- Attempt to require() each utility
+- Check for missing dependencies
+- Test exported functions
+- Classify as WORKING/FIXABLE/DEPRECATED based on errors
+
+### Step 2: Verify Integration Status
+
+Run integration scan to find utility usage:
+
+```bash
+# For each utility, count references in agents and tasks
+for util in .aios-core/scripts/*.js; do
+  name=$(basename $util .js)
+  count=$(grep -r "$name" .aios-core/agents .aios-core/tasks expansion-packs 2>/dev/null | wc -l)
+  echo "$name: $count references"
+done
+```
+
+### Step 3: Manual Classification Review
+
+For utilities with ambiguous status:
+- Review source code quality
+- Estimate completion percentage
+- Assess concept value
+- Calculate fix effort estimate
+
+### Step 4: Generate Priority Scoring
+
+For FIXABLE utilities, calculate priority score:
+
+```
+Priority Score = (Integration Count × 10) + (Completion % × 5) - (Fix Hours)
+```
+
+Higher scores = higher priority for fixing
+
+### Step 5: Make Story 3.19 Decision
+
+Determine if memory-layer capabilities exist:
+- Search for memory-related utilities
+- IF found AND classified FIXABLE:
+  - Estimate fix effort vs 20h threshold
+  - Assess core functionality completion (>60%?)
+  - Recommend GO/NO-GO/DEFER
+
+### Step 6: Generate Audit Report
+
+Create comprehensive report with:
+- Summary statistics (X WORKING, Y FIXABLE, Z DEPRECATED)
+- Per-utility details (status, errors, integration count, recommendation)
+- Fix priority list (ranked FIXABLE utilities)
+- Cleanup list (DEPRECATED utilities to remove)
+- Story 3.19 activation recommendation
+
+## Output
+
+**Primary**: `UTILITIES-AUDIT-REPORT.md` in project root or docs/
+
+**Format**:
+```markdown
+# Framework Utilities Audit Report
+
+## Executive Summary
+- Total Utilities: X
+- ✅ WORKING: Y (Z%)
+- 🔧 FIXABLE: A (B%)
+- 🗑️ DEPRECATED: C (D%)
+
+## Detailed Findings
+
+### WORKING Utilities
+...
+
+### FIXABLE Utilities (Priority Ranked)
+...
+
+### DEPRECATED Utilities (Cleanup Candidates)
+...
+
+## Story 3.19 Decision
+...
+```
+
+## Success Criteria
+
+- All 81 utilities audited without crashes
+- Classification is consistent and reproducible
+- Integration counts accurate
+- Report is actionable for Story 3.18 (cleanup)
+- Story 3.19 decision has clear rationale
+
+## Notes
+
+- Run from project root directory
+- Requires Node.js environment
+- May take 5-10 minutes for full audit
+- Some utilities may have circular dependencies - handle gracefully

package/.aios-core/development/tasks/bootstrap-shadcn-library.md

@@ -0,0 +1,286 @@
+# Bootstrap Shadcn/Radix Component Library
+
+> Task ID: atlas-bootstrap-shadcn  
+> Agent: Atlas (Design System Builder)  
+> 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: bootstrapShadcnLibrary()
+responsável: Uma (Empathizer)
+responsavel_type: Agente
+atomic_layer: Config
+
+**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: 2-10 min (estimated)
+cost_estimated: $0.001-0.008
+token_usage: ~800-2,500 tokens
+```
+
+**Optimization Notes:**
+- Validate configuration early; use atomic writes; implement rollback checkpoints
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Description
+
+Install and curate a Shadcn UI component library leveraging Tailwind v4, Radix primitives, and project design tokens. Establish shared utilities (`cn`, `cva`), Spinner/loading patterns, and documentation scaffold.
+
+## Prerequisites
+
+- Tailwind v4 configured with tokens (`@theme` + dark mode)
+- React/Next.js project with TypeScript
+- Node.js ≥ 18
+- Storybook (optional but recommended)
+
+## Workflow
+
+1. **Initialize Shadcn CLI**
+   ```bash
+   npx shadcn@latest init
+   ```
+   - Configure paths (`components`, `lib/utils.ts`)
+   - Enable TypeScript + Tailwind + Radix defaults
+
+2. **Install Core Utilities**
+   ```bash
+   npx shadcn@latest add button input card textarea badge skeleton spinner
+   ```
+   - Ensure `cn` helper uses `clsx` + `tailwind-merge`
+   - Add `Spinner` component for loading states (if not provided by template)
+
+3. **Map to Tokens**
+   - Replace hardcoded colors with semantic token classes (`bg-primary`, etc.)
+   - Align spacing/typography with design system scale
+   - Add dark mode variants (`dark:bg-background`)
+
+4. **Radix Integration**
+   - Install Radix primitives as required (`@radix-ui/react-slot`, etc.)
+   - Verify accessibility attributes and focus management remain intact
+
+5. **Variant & Utility Enhancements**
+   - Extend `cva` definitions to match project variants (density, destructive, ghost)
+   - Add shared loading pattern (Spinner + `isLoading` prop)
+   - Introduce compound variants for icon buttons, destructive actions
+
+6. **Documentation & Storybook**
+   - Create MDX or markdown docs for each component (`docs/components`)
+   - Optional: Add Storybook stories using auto-generated stories from `tasks/build-component`
+
+7. **Update State**
+   - Append to `.state.yaml` (`tooling.shadcn`) with components installed, timestamp
+   - Record any local overrides or follow-up actions
+
+## Deliverables
+
+- Populated `components/ui/` directory with Shadcn components
+- Updated `lib/utils.ts` (`cn`, `formatNumber`, etc. if needed)
+- Component documentation & Storybook stories (optional)
+- `.state.yaml` entries for `tooling.shadcn`
+
+## Success Criteria
+
+- [ ] Shadcn CLI initialized with Tailwind v4-compatible paths
+- [ ] Core components (button/input/card/etc.) installed and tokenized
+- [ ] `cn` helper + `class-variance-authority` configured
+- [ ] Spinner/loading pattern standardized across components
+- [ ] Documentation/Storybook updated with usage examples
+- [ ] `.state.yaml` reports bootstrap timestamp and component list
+
+## Error Handling
+
+- **CLI install failure**: Delete partial files, rerun `npx shadcn@latest init`
+- **Radix import mismatch**: Align versions with lockfile, reinstall packages
+- **Token mismatch**: Regenerate Tailwind classes or add missing semantic tokens
+- **Storybook build failure**: Update Storybook to latest (v8+) and re-run
+
+## Notes
+
+- Prefer named exports (`export { Button }`) for tree-shaking
+- Maintain parity between Shadcn variants and design token aliases
+- Document manual updates (Shadcn is copy/paste — no automatic updates)
+- Schedule regular audits to pull upstream improvements intentionally