aios-core 2.1.6 → 2.2.1

package/.aios-core/development/tasks/db-smoke-test.md

@@ -1,351 +1,351 @@
-# Task: DB Smoke Test
-
-**Purpose**: Run post-migration validation checks
-
-**Elicit**: false
-
----
-
-## Process
-
-## 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: dbSmokeTest()
-responsável: Dara (Sage)
-responsavel_type: Agente
-atomic_layer: Config
-
-**Entrada:**
-- campo: query
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Valid SQL query
-
-- campo: params
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Query parameters
-
-- campo: connection
-  tipo: object
-  origem: config
-  obrigatório: true
-  validação: Valid PostgreSQL connection via Supabase
-
-**Saída:**
-- campo: query_result
-  tipo: array
-  destino: Memory
-  persistido: false
-
-- campo: records_affected
-  tipo: number
-  destino: Return value
-  persistido: false
-
-- campo: execution_time
-  tipo: number
-  destino: Memory
-  persistido: false
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Database connection established; query syntax valid
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check database connection established; query syntax valid
-    error_message: "Pre-condition failed: Database connection established; query syntax valid"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Query executed; results returned; transaction committed
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify query executed; results returned; transaction committed
-    error_message: "Post-condition failed: Query executed; results returned; transaction committed"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Data persisted correctly; constraints respected; no orphaned data
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert data persisted correctly; constraints respected; no orphaned data
-    error_message: "Acceptance criterion not met: Data persisted correctly; constraints respected; no orphaned data"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** supabase
-  - **Purpose:** PostgreSQL database connection via Supabase client
-  - **Source:** @supabase/supabase-js
-
-- **Tool:** query-validator
-  - **Purpose:** SQL query syntax validation
-  - **Source:** .aios-core/utils/db-query-validator.js
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** db-query.js
-  - **Purpose:** Execute PostgreSQL queries with error handling via Supabase
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/db-query.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Connection Failed
-   - **Cause:** Unable to connect to Neo4j database
-   - **Resolution:** Check connection string, credentials, network
-   - **Recovery:** Retry with exponential backoff (max 3 attempts)
-
-2. **Error:** Query Syntax Error
-   - **Cause:** Invalid Cypher query syntax
-   - **Resolution:** Validate query syntax before execution
-   - **Recovery:** Return detailed syntax error, suggest fix
-
-3. **Error:** Transaction Rollback
-   - **Cause:** Query violates constraints or timeout
-   - **Resolution:** Review query logic and constraints
-   - **Recovery:** Automatic rollback, preserve data integrity
-
----
-
-## 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:
-  - database
-  - infrastructure
-updated_at: 2025-11-17
-```
-
----
-
-
-### 1. Locate Smoke Test File
-
-Check for smoke test in this order:
-
-1. `supabase/tests/smoke/v_current.sql` (project-specific)
-2. `supabase/tests/smoke_test.sql` (project-specific)
-3. `.aios-core/product/templates/tmpl-smoke-test.sql` (template)
-
-### 2. Run Smoke Test
-
-```bash
-SMOKE_TEST=""
-
-if [ -f "supabase/tests/smoke/v_current.sql" ]; then
-  SMOKE_TEST="supabase/tests/smoke/v_current.sql"
-elif [ -f "supabase/tests/smoke_test.sql" ]; then
-  SMOKE_TEST="supabase/tests/smoke_test.sql"
-elif [ -f ".aios-core/product/templates/tmpl-smoke-test.sql" ]; then
-  SMOKE_TEST=".aios-core/product/templates/tmpl-smoke-test.sql"
-else
-  echo "❌ No smoke test file found"
-  exit 1
-fi
-
-echo "Running smoke test: $SMOKE_TEST"
-psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 -f "$SMOKE_TEST"
-```
-
-### 3. Report Results
-
-**If successful:**
-```
-✅ Smoke Test Passed
-
-Checks completed:
-  ✓ Table count validation
-  ✓ Policy count validation
-  ✓ Function existence checks
-  ✓ Basic query sanity
-```
-
-**If failed:**
-```
-❌ Smoke Test Failed
-
-Review errors above and:
-  1. Check migration completeness
-  2. Verify RLS policies installed
-  3. Confirm functions created
-  4. Consider rollback if critical
-```
-
----
-
-## What Is Tested
-
-Basic smoke tests typically check:
-
-### Schema Objects
-- Expected tables exist
-- Expected views exist
-- Expected functions exist
-- Expected triggers exist
-
-### RLS Coverage
-- RLS enabled on sensitive tables
-- Policies exist and are named correctly
-- Basic RLS queries don't error
-
-### Data Integrity
-- Foreign keys valid
-- Check constraints valid
-- Sample queries return expected results
-
-### Performance
-- Basic queries complete in reasonable time
-- No missing indexes on FKs
-
----
-
-## Creating Custom Smoke Tests
-
-Create `supabase/tests/smoke/v_X_Y_Z.sql`:
-
-```sql
--- Smoke Test for v1.2.0
-SET client_min_messages = warning;
-
--- Table count
-SELECT COUNT(*) AS tables FROM information_schema.tables 
-WHERE table_schema='public';
--- Expected: 15
-
--- RLS enabled
-SELECT tablename FROM pg_tables 
-WHERE schemaname='public' AND rowsecurity = false;
--- Expected: empty (all tables have RLS)
-
--- Critical functions exist
-SELECT proname FROM pg_proc 
-WHERE pronamespace = 'public'::regnamespace
-AND proname IN ('function1', 'function2');
--- Expected: 2 rows
-
--- Sample data query
-SELECT COUNT(*) FROM users WHERE deleted_at IS NULL;
--- Expected: > 0
-
--- RLS sanity (doesn't error)
-SET LOCAL request.jwt.claims = '{"sub":"00000000-0000-0000-0000-000000000000","role":"authenticated"}';
-SELECT 1 FROM protected_table LIMIT 1;
-```
-
----
-
-## Best Practices
-
-1. **Version-specific tests** - Name by schema version
-2. **Fast execution** - Under 5 seconds
-3. **No side effects** - Read-only queries
-4. **Clear expectations** - Document expected results
-5. **Fail fast** - Use ON_ERROR_STOP
-
----
-
-## Next Steps After Pass
-
-✓ Migration validated  
-→ Update migration log  
-→ Run RLS audit: `*rls-audit`  
-→ Check performance: `*analyze-hotpaths`
-
-## Next Steps After Fail
-
-❌ Migration issues detected  
-→ Review errors  
-→ Consider rollback: `*rollback {snapshot}`  
-→ Fix migration  
-→ Retry
+# Task: DB Smoke Test
+
+**Purpose**: Run post-migration validation checks
+
+**Elicit**: false
+
+---
+
+## Process
+
+## 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: dbSmokeTest()
+responsável: Dara (Sage)
+responsavel_type: Agente
+atomic_layer: Config
+
+**Entrada:**
+- campo: query
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid SQL query
+
+- campo: params
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Query parameters
+
+- campo: connection
+  tipo: object
+  origem: config
+  obrigatório: true
+  validação: Valid PostgreSQL connection via Supabase
+
+**Saída:**
+- campo: query_result
+  tipo: array
+  destino: Memory
+  persistido: false
+
+- campo: records_affected
+  tipo: number
+  destino: Return value
+  persistido: false
+
+- campo: execution_time
+  tipo: number
+  destino: Memory
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Database connection established; query syntax valid
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check database connection established; query syntax valid
+    error_message: "Pre-condition failed: Database connection established; query syntax valid"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Query executed; results returned; transaction committed
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify query executed; results returned; transaction committed
+    error_message: "Post-condition failed: Query executed; results returned; transaction committed"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Data persisted correctly; constraints respected; no orphaned data
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert data persisted correctly; constraints respected; no orphaned data
+    error_message: "Acceptance criterion not met: Data persisted correctly; constraints respected; no orphaned data"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** supabase
+  - **Purpose:** PostgreSQL database connection via Supabase client
+  - **Source:** @supabase/supabase-js
+
+- **Tool:** query-validator
+  - **Purpose:** SQL query syntax validation
+  - **Source:** .aios-core/utils/db-query-validator.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** db-query.js
+  - **Purpose:** Execute PostgreSQL queries with error handling via Supabase
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/db-query.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Connection Failed
+   - **Cause:** Unable to connect to Neo4j database
+   - **Resolution:** Check connection string, credentials, network
+   - **Recovery:** Retry with exponential backoff (max 3 attempts)
+
+2. **Error:** Query Syntax Error
+   - **Cause:** Invalid Cypher query syntax
+   - **Resolution:** Validate query syntax before execution
+   - **Recovery:** Return detailed syntax error, suggest fix
+
+3. **Error:** Transaction Rollback
+   - **Cause:** Query violates constraints or timeout
+   - **Resolution:** Review query logic and constraints
+   - **Recovery:** Automatic rollback, preserve data integrity
+
+---
+
+## 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:
+  - database
+  - infrastructure
+updated_at: 2025-11-17
+```
+
+---
+
+
+### 1. Locate Smoke Test File
+
+Check for smoke test in this order:
+
+1. `supabase/tests/smoke/v_current.sql` (project-specific)
+2. `supabase/tests/smoke_test.sql` (project-specific)
+3. `.aios-core/product/templates/tmpl-smoke-test.sql` (template)
+
+### 2. Run Smoke Test
+
+```bash
+SMOKE_TEST=""
+
+if [ -f "supabase/tests/smoke/v_current.sql" ]; then
+  SMOKE_TEST="supabase/tests/smoke/v_current.sql"
+elif [ -f "supabase/tests/smoke_test.sql" ]; then
+  SMOKE_TEST="supabase/tests/smoke_test.sql"
+elif [ -f ".aios-core/product/templates/tmpl-smoke-test.sql" ]; then
+  SMOKE_TEST=".aios-core/product/templates/tmpl-smoke-test.sql"
+else
+  echo "❌ No smoke test file found"
+  exit 1
+fi
+
+echo "Running smoke test: $SMOKE_TEST"
+psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 -f "$SMOKE_TEST"
+```
+
+### 3. Report Results
+
+**If successful:**
+```
+✅ Smoke Test Passed
+
+Checks completed:
+  ✓ Table count validation
+  ✓ Policy count validation
+  ✓ Function existence checks
+  ✓ Basic query sanity
+```
+
+**If failed:**
+```
+❌ Smoke Test Failed
+
+Review errors above and:
+  1. Check migration completeness
+  2. Verify RLS policies installed
+  3. Confirm functions created
+  4. Consider rollback if critical
+```
+
+---
+
+## What Is Tested
+
+Basic smoke tests typically check:
+
+### Schema Objects
+- Expected tables exist
+- Expected views exist
+- Expected functions exist
+- Expected triggers exist
+
+### RLS Coverage
+- RLS enabled on sensitive tables
+- Policies exist and are named correctly
+- Basic RLS queries don't error
+
+### Data Integrity
+- Foreign keys valid
+- Check constraints valid
+- Sample queries return expected results
+
+### Performance
+- Basic queries complete in reasonable time
+- No missing indexes on FKs
+
+---
+
+## Creating Custom Smoke Tests
+
+Create `supabase/tests/smoke/v_X_Y_Z.sql`:
+
+```sql
+-- Smoke Test for v1.2.0
+SET client_min_messages = warning;
+
+-- Table count
+SELECT COUNT(*) AS tables FROM information_schema.tables 
+WHERE table_schema='public';
+-- Expected: 15
+
+-- RLS enabled
+SELECT tablename FROM pg_tables 
+WHERE schemaname='public' AND rowsecurity = false;
+-- Expected: empty (all tables have RLS)
+
+-- Critical functions exist
+SELECT proname FROM pg_proc 
+WHERE pronamespace = 'public'::regnamespace
+AND proname IN ('function1', 'function2');
+-- Expected: 2 rows
+
+-- Sample data query
+SELECT COUNT(*) FROM users WHERE deleted_at IS NULL;
+-- Expected: > 0
+
+-- RLS sanity (doesn't error)
+SET LOCAL request.jwt.claims = '{"sub":"00000000-0000-0000-0000-000000000000","role":"authenticated"}';
+SELECT 1 FROM protected_table LIMIT 1;
+```
+
+---
+
+## Best Practices
+
+1. **Version-specific tests** - Name by schema version
+2. **Fast execution** - Under 5 seconds
+3. **No side effects** - Read-only queries
+4. **Clear expectations** - Document expected results
+5. **Fail fast** - Use ON_ERROR_STOP
+
+---
+
+## Next Steps After Pass
+
+✓ Migration validated  
+→ Update migration log  
+→ Run RLS audit: `*rls-audit`  
+→ Check performance: `*analyze-hotpaths`
+
+## Next Steps After Fail
+
+❌ Migration issues detected  
+→ Review errors  
+→ Consider rollback: `*rollback {snapshot}`  
+→ Fix migration  
+→ Retry