codex-genesis-harness 0.1.1 → 0.1.4

package/.codex/skills/genesis-debug-guide/examples/example.md

@@ -0,0 +1,48 @@
+# Example: Debugging a Failing Unit Test
+
+## Scenario
+
+A unit test for the `UserService.createUser()` method suddenly fails with:
+
+```
+AssertionError: expected undefined but got "john@example.com"
+Expected: undefined
+Received: "john@example.com"
+```
+
+## Using genesis-debug-guide
+
+```
+/debug "UserService createUser test failing - expects undefined, gets email string"
+```
+
+## Workflow Executed
+
+1. **Isolation** — Run only the failing test:
+   ```bash
+   npx jest UserService.test.ts --testNamePattern="createUser"
+   ```
+
+2. **Mock inspection** — Found that mock setup for `EmailValidator` returns full user object instead of `null` for invalid input.
+
+3. **Root cause** — `EmailValidator` mock was updated to return `{ email }` but test still expected `undefined`.
+
+4. **Fix** — Updated mock to align with new `EmailValidator` interface:
+   ```ts
+   jest.mock('./EmailValidator', () => ({ validate: () => undefined }));
+   ```
+
+5. **Regression test** — Added assertion for both valid and invalid email inputs.
+
+6. **Verification** — Full test suite passes; debug log cleaned up.
+
+## Debug Investigation Log
+
+Saved to: `observability/agent-runs/debug-2026-05-31.md`
+
+## Outcome
+
+- ✅ Root cause documented
+- ✅ Fix minimal (1 line in test mock)
+- ✅ Regression test added
+- ✅ No debug code left in implementation

package/.codex/skills/genesis-debug-guide/observability/debug-commands.md

@@ -0,0 +1,365 @@
+# Debug Commands by Language
+
+Quick reference for debugging commands in different languages used in Genesis projects.
+
+---
+
+## Node.js / JavaScript
+
+### Console Methods
+```javascript
+// Information
+console.log('Message:', value);
+console.info('Info message');
+console.warn('Warning message');
+console.error('Error message');
+
+// Structured
+console.table([{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]);
+console.dir(object);
+
+// Timing
+console.time('label');
+// ... code ...
+console.timeEnd('label');  // Outputs: label: 1234.56ms
+
+// Assertions
+console.assert(condition, 'Message if assertion fails');
+
+// Trace
+console.trace('Stack trace at this point');
+
+// Groups
+console.group('Group label');
+console.log('...logs in group...');
+console.groupEnd();
+```
+
+### Debugging CLI
+```bash
+# Run with Node inspector
+node --inspect script.js
+node --inspect-brk script.js  # Breaks on first line
+
+# Run Jest with debugging
+node --inspect-brk node_modules/.bin/jest --runInBand test.js
+
+# Open Chrome DevTools: chrome://inspect
+```
+
+### Jest/Test Debugging
+```javascript
+test('example', () => {
+  debugger;  // Browser debugger breakpoint (if using inspect)
+  expect(value).toBe(expected);
+});
+
+// Skip a test
+test.skip('should do something', () => {});
+
+// Only run this test
+test.only('should do something', () => {});
+
+// Print all mocks
+console.log(jest.fn.mock.calls);
+```
+
+---
+
+## Python
+
+### Print Debugging
+```python
+print(f"Value: {value}")
+print(f"Type: {type(value)}")
+print(f"Dict keys: {obj.__dict__}")
+
+# Pretty print
+import pprint
+pprint.pprint(large_dict)
+
+# JSON
+import json
+print(json.dumps(obj, indent=2))
+```
+
+### Logging
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+logger.debug('Debug message')
+logger.info('Info message')
+logger.warning('Warning message')
+logger.error('Error message')
+
+# With context
+logger.info(f'Processing user {user_id}: {user.name}')
+```
+
+### Interactive Debugging
+```python
+# PDB - Python Debugger
+import pdb
+pdb.set_trace()  # Breakpoint - enters debugger here
+
+# Or:
+breakpoint()  # Python 3.7+
+
+# IPython for interactive shell
+from IPython import embed
+embed()  # Opens interactive IPython shell
+```
+
+### Testing
+```python
+import unittest
+
+# Skip test
+@unittest.skip("Not implemented")
+def test_something(self):
+    pass
+
+# Print test details
+python -m pytest -v -s test.py  # -v verbose, -s show print statements
+```
+
+---
+
+## PHP
+
+### Echo/Print
+```php
+echo "Simple output";
+print_r($array);         // For arrays/objects
+var_dump($variable);     // Detailed dump with types
+var_export($variable);   // Machine-readable format
+```
+
+### Error Reporting
+```php
+// Set error level
+ini_set('display_errors', 1);
+error_reporting(E_ALL);
+
+// Log to file
+error_log("Debug message", 3, "/tmp/debug.log");
+```
+
+### Debugging Tools
+```php
+// Xdebug extension (if installed)
+var_dump($variable);  // With Xdebug: shows enhanced output
+
+// Fire up debugger breakpoint
+xdebug_break();
+
+// Stack trace
+debug_backtrace();
+```
+
+### Laravel Specific
+```php
+// Log helper
+\Log::debug('Message', ['key' => $value]);
+\Log::channel('single')->debug('Message');
+
+// Dump and die
+dd($variable);
+
+// Dump without dying
+dump($variable);
+```
+
+---
+
+## Ruby
+
+### Print Debugging
+```ruby
+puts "Message: #{value}"
+p variable           # Inspect format (like Ruby console)
+pp object            # Pretty print (requires 'pp')
+```
+
+### Debugging
+```ruby
+# Byebug debugger
+require 'byebug'
+byebug  # Breakpoint - enters debugger
+
+# Pry (better interactive console)
+require 'pry'
+binding.pry  # Open Pry console here
+
+# Interactive shell
+irb  # Interactive Ruby shell
+```
+
+### Logging
+```ruby
+require 'logger'
+logger = Logger.new(STDOUT)
+logger.debug("Debug message")
+logger.info("Info message")
+
+# Rails logging
+Rails.logger.debug("Message")
+```
+
+### Testing
+```bash
+# Run single test
+ruby -I lib test/test_name.rb
+
+# Run with debugging
+ruby -r pry -I lib test/test_name.rb
+
+# Rspec with debugging
+rspec test_file.rb --format documentation
+rspec test_file.rb -e "test name"  # Run specific test
+```
+
+---
+
+## Go
+
+### Logging
+```go
+import "log"
+
+log.Println("Standard output")
+log.Printf("Formatted: %v, %s", value, text)
+log.Fatalf("Fatal error: %v", err)  // Prints and exits
+
+// Structured logging (with external package)
+import "github.com/sirupsen/logrus"
+log.WithField("user_id", id).Debug("User action")
+```
+
+### Debugging
+```go
+// Delve debugger
+import _ "net/http/pprof"
+
+// Profiling
+import "runtime/pprof"
+```
+
+### Testing
+```bash
+# Run tests with verbose output
+go test -v ./...
+
+# Run single test
+go test -run TestName ./...
+
+# Show coverage
+go test -cover ./...
+
+# Debug test with dlv
+dlv test ./package -- -test.v -test.run TestName
+```
+
+---
+
+## System / Performance Debugging
+
+### Check System Load
+```bash
+# Unix/Linux/macOS
+top                 # Real-time CPU/Memory usage
+htop                # Better interface for top
+ps aux              # List all processes
+uptime              # System load average
+
+# Network
+netstat -tuln       # Listen ports
+lsof -i :8000       # Processes using port 8000
+
+# File I/O
+iotop               # I/O by process
+```
+
+### Check Application Ports
+```bash
+# See if port is in use
+lsof -i :3000
+netstat -tulpn | grep 3000
+
+# Kill process on port
+kill -9 $(lsof -t -i :3000)
+```
+
+### Trace System Calls
+```bash
+# Linux
+strace command      # Show system calls
+strace -e trace=network command  # Network calls only
+
+# macOS
+dtruss command      # Similar to strace
+```
+
+---
+
+## Browser DevTools
+
+### Chrome/Edge DevTools
+```javascript
+// Keyboard shortcuts
+F12 or Ctrl+Shift+I         // Open DevTools
+Ctrl+Shift+J                // Console
+Ctrl+Shift+C                // Element picker
+Ctrl+Shift+M                // Device mode
+
+// Console commands
+console.log(...)
+console.time('label')
+console.assert(condition, 'message')
+```
+
+### Break on Error
+```javascript
+// Pause on all exceptions
+DevTools → Sources → Pause on exceptions (icon with triangle)
+
+// Break on specific line
+DevTools → Sources → Click line number to set breakpoint
+
+// Conditional breakpoint
+Right-click line → Add conditional breakpoint → Condition
+```
+
+---
+
+## Environment Inspection
+
+### Check Environment
+```bash
+# Node.js
+node -e "console.log(process.versions)"
+
+# Python
+python -c "import sys; print(sys.version)"
+
+# Check installed packages
+npm list                    # Node
+pip list                    # Python
+gem list                    # Ruby
+```
+
+### Debug Environment Variables
+```bash
+# Show all env vars
+env | sort
+echo $PATH
+
+# Node.js
+console.log(process.env.NODE_ENV)
+
+# Python
+import os
+print(os.environ.get('DATABASE_URL'))
+```

package/.codex/skills/genesis-debug-guide/playbooks/unit-test-failures.md

@@ -0,0 +1,289 @@
+# Unit Test Failures - Debugging Playbook
+
+**Purpose**: Systematic approach to debugging unit test failures. Unit tests are isolated and deterministic, so failures are usually in test setup, mocks, or implementation logic.
+
+**Trigger**: When a unit test fails consistently
+
+**Duration**: 5-15 minutes typically
+
+---
+
+## Step 1: Isolate the Failure (2-3 min)
+
+```bash
+# Run ONLY the failing test
+npm test -- path/to/test.test.js
+
+# Verify it fails every time
+npm test -- path/to/test.test.js
+npm test -- path/to/test.test.js
+```
+
+**Check**:
+- ✅ Fails same way every run? → Deterministic, proceed
+- ❌ Fails sometimes? → See flaky-test-investigation.md
+- ❌ Passes on retry? → Environment issue, check dependencies
+
+---
+
+## Step 2: Understand the Failure (2-3 min)
+
+Read the error message **completely**:
+
+```
+FAIL src/utils/__tests__/parseDate.test.js
+  parseDate()
+    ✓ should parse valid ISO date
+    ✗ should return null for invalid date
+      Expected: null
+      Received: "Invalid Date"
+      at Object.<anonymous> (src/utils/__tests__/parseDate.test.js:15:5)
+```
+
+**Extract**:
+- Test name: "should return null for invalid date"
+- Expected: `null`
+- Received: `"Invalid Date"` (string, not null!)
+- File & line: `parseDate.test.js:15`
+
+---
+
+## Step 3: Review Test Code (3-4 min)
+
+Open the test file and find the failing test:
+
+```javascript
+// parseDate.test.js line 15
+test('should return null for invalid date', () => {
+  const result = parseDate('not-a-date');
+  expect(result).toBe(null);  // ← Expectation at line 15
+});
+```
+
+**Questions**:
+- [ ] Is test setup correct? (line 1-5)
+- [ ] Are mocks configured properly? (if any)
+- [ ] Is the assertion testing the right thing?
+- [ ] Could test data be wrong?
+
+---
+
+## Step 4: Review Implementation (3-4 min)
+
+Find the function being tested:
+
+```javascript
+// parseDate.js
+export function parseDate(dateString) {
+  const date = new Date(dateString);
+  if (isNaN(date.getTime())) {
+    return 'Invalid Date';  // ← BUG! Should return null
+  }
+  return date;
+}
+```
+
+**Questions**:
+- [ ] Does function return correct type? (null vs "Invalid Date")
+- [ ] Does logic match test expectations?
+- [ ] Are there other callers expecting different behavior?
+- [ ] Any recent changes to this function? (git blame)
+
+---
+
+## Step 5: Fix the Bug (1-2 min)
+
+**Option A: Fix is in implementation**
+```javascript
+// WRONG: returns string
+return 'Invalid Date';
+
+// CORRECT: returns null
+return null;
+```
+
+**Option B: Fix is in test**
+```javascript
+// If implementation is correct, test is wrong
+expect(result).toBe('Invalid Date');  // Update test
+```
+
+**Option C: Fix is in mock setup**
+```javascript
+// Mock not configured correctly
+const mockFetch = jest.fn().mockResolvedValue({ ok: true });
+```
+
+**Rule**: Fix only ONE thing per fix. Don't refactor while fixing.
+
+---
+
+## Step 6: Verify Fix (1-2 min)
+
+```bash
+# Run failing test - should now PASS
+npm test -- path/to/test.test.js
+
+# Run full test suite - all should PASS
+npm test
+
+# Check: no new failures
+# Check: no debug code left (console.log, debugger)
+```
+
+---
+
+## Step 7: Add Prevention (2-3 min)
+
+**Similar bugs to prevent**:
+- [ ] Add test for related edge cases
+- [ ] Add test for null/undefined inputs
+- [ ] Add test for wrong type inputs
+- [ ] Add test for boundary values
+
+```javascript
+test('should handle null input', () => {
+  expect(parseDate(null)).toBe(null);
+});
+
+test('should handle undefined input', () => {
+  expect(parseDate(undefined)).toBe(null);
+});
+
+test('should handle empty string', () => {
+  expect(parseDate('')).toBe(null);
+});
+```
+
+---
+
+## Common Unit Test Issues
+
+### 1. Mock Not Configured
+```javascript
+// ❌ WRONG: mock returns undefined
+const mock = jest.fn();
+
+// ✅ CORRECT: mock returns expected value
+const mock = jest.fn().mockReturnValue({ id: 1, name: 'Test' });
+```
+
+### 2. Wrong Import
+```javascript
+// ❌ WRONG: importing test mock
+import parseDate from './parseDate.mock.js';
+
+// ✅ CORRECT: importing actual implementation
+import { parseDate } from './parseDate.js';
+```
+
+### 3. Test Data Type Mismatch
+```javascript
+// ❌ WRONG: passing wrong type
+parseDate(123456);  // Passing number, expects string
+
+// ✅ CORRECT: passing correct type
+parseDate('2024-01-01');  // Passing string
+```
+
+### 4. Shared State Between Tests
+```javascript
+// ❌ WRONG: variable shared across tests
+let counter = 0;
+test('test 1', () => { counter++; });
+test('test 2', () => { expect(counter).toBe(1); });  // Fails if test 1 ran first!
+
+// ✅ CORRECT: each test has isolated state
+test('test 1', () => { const counter = 0; counter++; });
+test('test 2', () => { const counter = 0; expect(counter).toBe(0); });
+```
+
+### 5. Async/Promise Not Awaited
+```javascript
+// ❌ WRONG: not waiting for promise
+test('should fetch user', () => {
+  fetchUser(1);  // Returns promise, but not awaited
+  expect(result).toBe(...);  // Runs before promise resolves!
+});
+
+// ✅ CORRECT: await promise or return from test
+test('should fetch user', async () => {
+  const result = await fetchUser(1);
+  expect(result).toBe(...);
+});
+```
+
+---
+
+## Debugging Strategy by Test Type
+
+### Simple Unit (pure function)
+1. Check inputs match implementation
+2. Check return type
+3. Check logic handles edge cases
+4. Add edge case tests
+
+### Function with Dependencies
+1. Check mocks are configured
+2. Check mock is called correctly
+3. Check mock return value used
+4. Verify mock reset between tests
+
+### Class/Object Method
+1. Check class instantiation
+2. Check method parameters
+3. Check state after method call
+4. Check side effects (if any)
+
+---
+
+## Recovery: Still Can't Find Bug?
+
+If stuck for >10 minutes:
+
+1. **Add debug logging**:
+   ```javascript
+   test('test name', () => {
+     console.log('Input:', input);
+     const result = parseDate(input);
+     console.log('Result:', result);
+     console.log('Expected:', expectedValue);
+     expect(result).toBe(expectedValue);
+   });
+   ```
+
+2. **Simplify test**:
+   ```javascript
+   // Remove test setup, use hardcoded values
+   test('test name', () => {
+     const result = parseDate('2024-01-01');
+     expect(result).toEqual({ year: 2024, month: 1, day: 1 });
+   });
+   ```
+
+3. **Check git history**:
+   ```bash
+   git log -p -- path/to/test.js
+   git log -p -- path/to/implementation.js
+   ```
+
+4. **Run with debugging**:
+   ```bash
+   node --inspect-brk node_modules/.bin/jest --runInBand path/to/test.js
+   # Opens Chrome DevTools for debugging
+   ```
+
+---
+
+## Checklist: Ready to Complete
+
+- [ ] Test fails in isolation
+- [ ] Error message understood
+- [ ] Test code reviewed
+- [ ] Implementation reviewed
+- [ ] Bug fixed (one thing only)
+- [ ] Test passes
+- [ ] Full suite passes
+- [ ] No debug code left
+- [ ] Edge case tests added
+- [ ] Ready to commit