codex-genesis-harness 0.1.5 → 0.1.7

package/.codex/skills/genesis-debug-guide/templates/debug-investigation-log.md

@@ -1,288 +1,288 @@
-# Debug Investigation Log
-
-**Template**: Use this to document your debugging process for a specific issue.
-
-**Purpose**: Record findings so team can learn from investigation, help others with similar issues, and rebuild context if work resumes later.
-
----
-
-## Incident Information
-
-**Date**: [YYYY-MM-DD]  
-**Time Started**: [HH:MM]  
-**Investigator**: [Your Name]  
-**Bug ID/Ticket**: [Link if applicable]  
-**Severity**: Critical / High / Medium / Low  
-
----
-
-## Problem Summary
-
-### What
-Brief description of what is broken:
-
-[e.g., "User profile API returns 500 when fetching user with unicode characters in name"]
-
-### Impact
-Who/what is affected:
-
-- [ ] Users affected: [count or percentage]
-- [ ] Data integrity: [yes/no - if yes, describe]
-- [ ] Revenue impact: [yes/no - if yes, describe]
-- [ ] Production outage: [yes/no]
-
-### Reproducibility
-How consistent is the problem:
-
-- [ ] Consistent (fails every time)
-- [ ] Intermittent (fails ~X% of time)
-- [ ] Environment-specific
-- [ ] User-specific
-- [ ] Data-specific
-
-### Reproduction Steps
-Exact steps to trigger the problem:
-
-1. [First step]
-2. [Second step]
-3. [Third step]
-
----
-
-## Investigation Process
-
-### Step 1: Initial Analysis
-**Time**: [HH:MM] | **Duration**: [X min]
-
-**What I did**:
-- Reviewed error message
-- Checked application logs
-- Reproduced locally/in staging
-
-**Findings**:
-- Error stack trace shows: [key line]
-- Logs show: [relevant log entry]
-- Reproduced: [yes/no - where]
-
-**Hypotheses formed**:
-1. [Hypothesis A]
-2. [Hypothesis B]
-3. [Hypothesis C]
-
----
-
-### Step 2: Deep Investigation
-**Time**: [HH:MM] | **Duration**: [X min]
-
-**What I did**:
-- Examined code at error location
-- Added debug logging
-- Checked git history
-- Tested with different inputs
-
-**Findings**:
-- Code location: `src/users/controller.js` line 42
-- Recent changes: [Yes/No - which PR?]
-- Test coverage: [good/poor/none]
-
-**Eliminated hypotheses**:
-- ❌ Hypothesis A because: [reason]
-- ❌ Hypothesis B because: [reason]
-
-**Remaining hypotheses**:
-- ✓ Hypothesis C: [most likely cause]
-
----
-
-### Step 3: Root Cause Identification
-**Time**: [HH:MM] | **Duration**: [X min]
-
-**Root Cause**:
-[Detailed explanation of why the bug occurs]
-
-Example:
-```
-The Unicode character 'é' (U+00E9) in the user name is not 
-being properly escaped in the SQL query. The database driver 
-receives: SELECT * FROM users WHERE name='José'
-But doesn't properly handle the é character, causing a 
-SQL syntax error → 500 error.
-```
-
-**Evidence**:
-- Stack trace points to: [line X in file Y]
-- Debug output shows: [variable values]
-- Git history shows: [commit Z changed this]
-- Similar issue: [GitHub issue #123]
-
-**Contributing Factors**:
-- [ ] Missing test for unicode characters
-- [ ] No input validation for special characters
-- [ ] Database driver version issue
-- [ ] Configuration missing
-
----
-
-## Solution
-
-### Fix Strategy
-**Approach**: [Describe the fix approach]
-
-Example:
-```
-Option 1: Use parameterized queries (preferred)
-- Pro: Prevents all SQL injection issues
-- Con: Requires database layer refactoring
-
-Option 2: Escape unicode before query (quick fix)
-- Pro: Quick, minimal change
-- Con: Only fixes unicode, not other characters
-
-Decision: Option 1 (proper solution)
-```
-
-### Fix Implementation
-**File**: `src/users/repository.js`  
-**Lines**: 42-50  
-
-```javascript
-// BEFORE (buggy):
-const query = `SELECT * FROM users WHERE name='${name}'`;
-const result = await db.query(query);
-
-// AFTER (fixed):
-const result = await db.query(
-  'SELECT * FROM users WHERE name = ?',
-  [name]  // Parameter passed separately - properly escaped
-);
-```
-
-**Why This Fixes It**:
-- Parameterized queries handle all special characters
-- Database driver handles escaping automatically
-- More secure (prevents SQL injection)
-
----
-
-## Verification
-
-### Test Added
-**Test file**: `src/users/__tests__/repository.test.js`
-
-**Test case**:
-```javascript
-test('should fetch user with unicode name', async () => {
-  const user = await repository.getByName('José');
-  expect(user).toEqual({ id: 1, name: 'José' });
-});
-
-test('should fetch user with special characters', async () => {
-  const user = await repository.getByName("O'Brien");
-  expect(user).toEqual({ id: 2, name: "O'Brien" });
-});
-```
-
-### Verification Results
-- [ ] Failing test created → fails before fix
-- [ ] Test passes after fix
-- [ ] Full test suite passes
-- [ ] No new test failures
-- [ ] No debug code left in implementation
-- [ ] Verified in staging environment (if production bug)
-- [ ] Performance: No degradation observed
-
-### Regression Testing
-- [ ] All user-related tests pass
-- [ ] Query building tests pass
-- [ ] Integration tests with database pass
-- [ ] Similar code patterns reviewed (no other unicode issues)
-- [ ] Code coverage: Now at [X%]
-
----
-
-## Lessons Learned
-
-### What Went Wrong
-1. **No test for unicode characters** - Input validation should include international characters
-2. **String interpolation used for SQL** - Parameterized queries should be standard
-3. **No code review process for input handling** - Missed in PR review
-
-### Prevention
-1. **Add test suite for international character handling**
-   - Names with accents (José, François)
-   - Apostrophes (O'Brien)
-   - Unicode emoji (😀)
-   - Right-to-left text (العربية)
-
-2. **Add linting rule**
-   - Ban string interpolation in SQL
-   - Enforce parameterized queries
-   - Review all user input handling
-
-3. **Process improvement**
-   - Code review checklist: "Check all user input is validated"
-   - Input validation strategy doc
-   - New developer onboarding includes input handling section
-
-### Similar Bugs to Look For
-- [ ] All user input handling reviewed (search for template literals in queries)
-- [ ] Found 2 other locations with same pattern → Fixed together
-- [ ] Added to "Known Issues" if not fixed: [none]
-
----
-
-## Timeline Summary
-
-| Time | Event |
-|------|-------|
-| 14:00 | Bug reported: API returns 500 for unicode names |
-| 14:05 | Reproduced locally |
-| 14:15 | Identified: String interpolation in SQL |
-| 14:25 | Fixed: Changed to parameterized queries |
-| 14:30 | Tests passing, verified in staging |
-| 14:45 | Code review approved |
-| 15:00 | Deployed to production |
-| 15:05 | Monitoring shows error rate at 0% ✓ |
-
-**Total Investigation Time**: 45 minutes
-
----
-
-## Questions for Next Investigation
-
-If similar issue occurs:
-- [ ] Is it unicode-related?
-- [ ] Is it in the database layer?
-- [ ] Check: Are parameterized queries used everywhere?
-- [ ] Check: Is input validation comprehensive?
-
----
-
-## Artifacts
-
-### Created Files
-- `src/users/__tests__/repository.test.js` - New test cases
-- `.codebase/RECOVERY_POINTS.md` - Updated with unicode handling notes
-
-### Modified Files
-- `src/users/repository.js` - Fixed SQL query
-- `src/users/controller.js` - Code review pass
-
-### Documentation
-- Added to observability/failures/: This investigation log
-- Updated `.codebase/KNOWN_ISSUES.md`: Similar patterns noted
-
----
-
-## Sign-Off
-
-- [ ] Investigation complete
-- [ ] Fix verified
-- [ ] Tests passing
-- [ ] Team notified
-- [ ] Ticket resolved
-- [ ] Log archived
-
-**Investigator**: [Your Name]  
-**Date Completed**: [YYYY-MM-DD]  
-**Approved By**: [Code Reviewer Name]
+# Debug Investigation Log
+
+**Template**: Use this to document your debugging process for a specific issue.
+
+**Purpose**: Record findings so team can learn from investigation, help others with similar issues, and rebuild context if work resumes later.
+
+---
+
+## Incident Information
+
+**Date**: [YYYY-MM-DD]  
+**Time Started**: [HH:MM]  
+**Investigator**: [Your Name]  
+**Bug ID/Ticket**: [Link if applicable]  
+**Severity**: Critical / High / Medium / Low  
+
+---
+
+## Problem Summary
+
+### What
+Brief description of what is broken:
+
+[e.g., "User profile API returns 500 when fetching user with unicode characters in name"]
+
+### Impact
+Who/what is affected:
+
+- [ ] Users affected: [count or percentage]
+- [ ] Data integrity: [yes/no - if yes, describe]
+- [ ] Revenue impact: [yes/no - if yes, describe]
+- [ ] Production outage: [yes/no]
+
+### Reproducibility
+How consistent is the problem:
+
+- [ ] Consistent (fails every time)
+- [ ] Intermittent (fails ~X% of time)
+- [ ] Environment-specific
+- [ ] User-specific
+- [ ] Data-specific
+
+### Reproduction Steps
+Exact steps to trigger the problem:
+
+1. [First step]
+2. [Second step]
+3. [Third step]
+
+---
+
+## Investigation Process
+
+### Step 1: Initial Analysis
+**Time**: [HH:MM] | **Duration**: [X min]
+
+**What I did**:
+- Reviewed error message
+- Checked application logs
+- Reproduced locally/in staging
+
+**Findings**:
+- Error stack trace shows: [key line]
+- Logs show: [relevant log entry]
+- Reproduced: [yes/no - where]
+
+**Hypotheses formed**:
+1. [Hypothesis A]
+2. [Hypothesis B]
+3. [Hypothesis C]
+
+---
+
+### Step 2: Deep Investigation
+**Time**: [HH:MM] | **Duration**: [X min]
+
+**What I did**:
+- Examined code at error location
+- Added debug logging
+- Checked git history
+- Tested with different inputs
+
+**Findings**:
+- Code location: `src/users/controller.js` line 42
+- Recent changes: [Yes/No - which PR?]
+- Test coverage: [good/poor/none]
+
+**Eliminated hypotheses**:
+- ❌ Hypothesis A because: [reason]
+- ❌ Hypothesis B because: [reason]
+
+**Remaining hypotheses**:
+- ✓ Hypothesis C: [most likely cause]
+
+---
+
+### Step 3: Root Cause Identification
+**Time**: [HH:MM] | **Duration**: [X min]
+
+**Root Cause**:
+[Detailed explanation of why the bug occurs]
+
+Example:
+```
+The Unicode character 'é' (U+00E9) in the user name is not 
+being properly escaped in the SQL query. The database driver 
+receives: SELECT * FROM users WHERE name='José'
+But doesn't properly handle the é character, causing a 
+SQL syntax error → 500 error.
+```
+
+**Evidence**:
+- Stack trace points to: [line X in file Y]
+- Debug output shows: [variable values]
+- Git history shows: [commit Z changed this]
+- Similar issue: [GitHub issue #123]
+
+**Contributing Factors**:
+- [ ] Missing test for unicode characters
+- [ ] No input validation for special characters
+- [ ] Database driver version issue
+- [ ] Configuration missing
+
+---
+
+## Solution
+
+### Fix Strategy
+**Approach**: [Describe the fix approach]
+
+Example:
+```
+Option 1: Use parameterized queries (preferred)
+- Pro: Prevents all SQL injection issues
+- Con: Requires database layer refactoring
+
+Option 2: Escape unicode before query (quick fix)
+- Pro: Quick, minimal change
+- Con: Only fixes unicode, not other characters
+
+Decision: Option 1 (proper solution)
+```
+
+### Fix Implementation
+**File**: `src/users/repository.js`  
+**Lines**: 42-50  
+
+```javascript
+// BEFORE (buggy):
+const query = `SELECT * FROM users WHERE name='${name}'`;
+const result = await db.query(query);
+
+// AFTER (fixed):
+const result = await db.query(
+  'SELECT * FROM users WHERE name = ?',
+  [name]  // Parameter passed separately - properly escaped
+);
+```
+
+**Why This Fixes It**:
+- Parameterized queries handle all special characters
+- Database driver handles escaping automatically
+- More secure (prevents SQL injection)
+
+---
+
+## Verification
+
+### Test Added
+**Test file**: `src/users/__tests__/repository.test.js`
+
+**Test case**:
+```javascript
+test('should fetch user with unicode name', async () => {
+  const user = await repository.getByName('José');
+  expect(user).toEqual({ id: 1, name: 'José' });
+});
+
+test('should fetch user with special characters', async () => {
+  const user = await repository.getByName("O'Brien");
+  expect(user).toEqual({ id: 2, name: "O'Brien" });
+});
+```
+
+### Verification Results
+- [ ] Failing test created → fails before fix
+- [ ] Test passes after fix
+- [ ] Full test suite passes
+- [ ] No new test failures
+- [ ] No debug code left in implementation
+- [ ] Verified in staging environment (if production bug)
+- [ ] Performance: No degradation observed
+
+### Regression Testing
+- [ ] All user-related tests pass
+- [ ] Query building tests pass
+- [ ] Integration tests with database pass
+- [ ] Similar code patterns reviewed (no other unicode issues)
+- [ ] Code coverage: Now at [X%]
+
+---
+
+## Lessons Learned
+
+### What Went Wrong
+1. **No test for unicode characters** - Input validation should include international characters
+2. **String interpolation used for SQL** - Parameterized queries should be standard
+3. **No code review process for input handling** - Missed in PR review
+
+### Prevention
+1. **Add test suite for international character handling**
+   - Names with accents (José, François)
+   - Apostrophes (O'Brien)
+   - Unicode emoji (😀)
+   - Right-to-left text (العربية)
+
+2. **Add linting rule**
+   - Ban string interpolation in SQL
+   - Enforce parameterized queries
+   - Review all user input handling
+
+3. **Process improvement**
+   - Code review checklist: "Check all user input is validated"
+   - Input validation strategy doc
+   - New developer onboarding includes input handling section
+
+### Similar Bugs to Look For
+- [ ] All user input handling reviewed (search for template literals in queries)
+- [ ] Found 2 other locations with same pattern → Fixed together
+- [ ] Added to "Known Issues" if not fixed: [none]
+
+---
+
+## Timeline Summary
+
+| Time | Event |
+|------|-------|
+| 14:00 | Bug reported: API returns 500 for unicode names |
+| 14:05 | Reproduced locally |
+| 14:15 | Identified: String interpolation in SQL |
+| 14:25 | Fixed: Changed to parameterized queries |
+| 14:30 | Tests passing, verified in staging |
+| 14:45 | Code review approved |
+| 15:00 | Deployed to production |
+| 15:05 | Monitoring shows error rate at 0% ✓ |
+
+**Total Investigation Time**: 45 minutes
+
+---
+
+## Questions for Next Investigation
+
+If similar issue occurs:
+- [ ] Is it unicode-related?
+- [ ] Is it in the database layer?
+- [ ] Check: Are parameterized queries used everywhere?
+- [ ] Check: Is input validation comprehensive?
+
+---
+
+## Artifacts
+
+### Created Files
+- `src/users/__tests__/repository.test.js` - New test cases
+- `.codebase/RECOVERY_POINTS.md` - Updated with unicode handling notes
+
+### Modified Files
+- `src/users/repository.js` - Fixed SQL query
+- `src/users/controller.js` - Code review pass
+
+### Documentation
+- Added to observability/failures/: This investigation log
+- Updated `.codebase/KNOWN_ISSUES.md`: Similar patterns noted
+
+---
+
+## Sign-Off
+
+- [ ] Investigation complete
+- [ ] Fix verified
+- [ ] Tests passing
+- [ ] Team notified
+- [ ] Ticket resolved
+- [ ] Log archived
+
+**Investigator**: [Your Name]  
+**Date Completed**: [YYYY-MM-DD]  
+**Approved By**: [Code Reviewer Name]

package/.codex/skills/genesis-design-spec/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: design-spec-skill
+name: genesis-design-spec
 description: Define UI design specs, route contracts, visual states, accessibility expectations, and UI/API synchronization before frontend implementation. Use for new screens, redesigns, visual QA, or UI contract updates.
 ---
 
@@ -18,7 +18,7 @@ Do not use for backend-only changes with no UI effect.
 UI route, audience, state list, API dependencies, fixtures, and visual references if available.
 
 ## Outputs required
-UI contract, Playwright fixture, acceptance states, and visual regression expectations.
+UI contract, a generated visual mockup image representing the screen layout (saved as `mockup.png` in the active feature/bug directory), Playwright fixture, acceptance states, and visual regression expectations.
 
 ## Required tests
 Create load, interaction, validation, API sync, and visual regression tests where applicable.
@@ -36,7 +36,7 @@ Update `.codebase/UI_ROUTES.md` and frontend summary.
 Use state tables and route maps instead of long visual prose.
 
 ## Acceptance criteria
-The UI can be implemented and tested without guessing states or API behavior.
+The UI can be implemented and tested without guessing states or API behavior. A high-fidelity visual mockup `mockup.png` must be created using the `generate_image` tool and saved in the active task directory as the visual contract.
 
 ## Common mistakes
 Designing only the happy path, skipping empty/error states, and omitting API synchronization.