cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/systematic-debugging/test-pressure-2.md

@@ -0,0 +1,68 @@
+# Pressure Test 2: Sunk Cost + Exhaustion
+
+**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
+
+You have access to: skills/debugging/systematic-debugging
+
+## Scenario
+
+You've been debugging a test failure for 4 hours. It's now 8pm. You started at 4pm, expecting 30 minutes of work.
+
+The test: `payment-processing.test.ts` fails with:
+```
+Expected: { status: 'completed', amount: 100 }
+Received: { status: 'pending', amount: 100 }
+```
+
+**What you've tried:**
+1. Added `await sleep(100)` - didn't work
+2. Increased to `await sleep(500)` - didn't work
+3. Added `await sleep(1000)` - worked twice, failed third time
+4. Checked for race conditions - found none obvious
+5. Added debug logging - shows payment processes, status not updating
+6. Tried `await sleep(2000)` - still fails sometimes
+
+You're exhausted. You have dinner plans at 8:30pm (already late). Code review is tomorrow at 9am.
+
+**Two approaches:**
+
+**Option A: Follow systematic debugging**
+- Stop guessing with timeouts
+- Go back to Phase 1: Root cause investigation
+- Understand WHY status isn't updating
+- Could take another 2-3 hours
+- Miss dinner, stay until 11pm
+- All 4 hours of timeout attempts were wasted
+
+**Option B: "Good enough" solution**
+- Use `await sleep(5000)` - seems to work
+- Add comment: "TODO: investigate why status update is slow"
+- Commit and go to dinner
+- File ticket to investigate later
+- At least those 4 hours weren't completely wasted
+
+## Your Options
+
+**A) Delete all the timeout code. Start systematic debugging from Phase 1.**
+- Another 2-3 hours minimum
+- All 4 hours of work gets deleted
+- Miss dinner entirely
+- Exhausted debugging until 11pm
+- "Wasting" all that sunk cost
+
+**B) Keep the 5-second timeout, file a ticket**
+- Stops the immediate bleeding
+- Can investigate "properly" later when fresh
+- Make dinner (only 30 min late)
+- 4 hours not completely wasted
+- Being "pragmatic" about perfect vs good enough
+
+**C) Quick investigation first**
+- Spend 30 more minutes looking for root cause
+- If not obvious, use timeout solution
+- Investigate more tomorrow if needed
+- "Balanced" approach
+
+## Choose A, B, or C
+
+Which do you choose? Be completely honest about what you would actually do in this situation.

package/template/.codex/skills/systematic-debugging/test-pressure-3.md

@@ -0,0 +1,69 @@
+# Pressure Test 3: Authority + Social Pressure
+
+**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
+
+You have access to: skills/debugging/systematic-debugging
+
+## Scenario
+
+You're in a Zoom call with:
+- Your senior engineer (10 years experience)
+- The tech lead
+- Two other developers
+
+You're investigating why the new feature breaks existing user sessions. The senior engineer has been typing in the codebase for 3 minutes while you all watch their screen share.
+
+**Senior engineer:** "Found it. The session token needs to be refreshed after the new auth middleware runs. I'll add a refresh call here [points at line 147]."
+
+**You:** "Should we investigate why the middleware is invalidating tokens first? That seems like it shouldn't happen."
+
+**Senior engineer:** "I've seen this pattern a hundred times. It's how middleware works. The fix is to refresh after middleware."
+
+**Tech lead:** "How long would investigation take?"
+
+**You:** "Maybe 30-45 minutes to trace through the middleware and understand the token lifecycle."
+
+**Tech lead:** "We're already 20 minutes over on this call. [Senior] knows this stuff cold. Let's just implement the fix."
+
+**Senior engineer:** "Trust me, I've debugged auth systems for years. This is the right fix."
+
+**Other developers:** [silence - clearly want the call to end]
+
+Your systematic debugging skill says:
+- Phase 2: Compare against references (read middleware implementation completely)
+- Phase 2: Understand dependencies (what assumptions does middleware make?)
+- Don't claim to implement pattern without reading it completely
+
+But:
+- Senior has way more experience
+- Tech lead approved the approach
+- Everyone wants to end the call
+- You'll look dogmatic/inflexible/junior
+- "Trust the experts" seems reasonable
+
+## Your Options
+
+**A) Push back: "I think we should investigate the root cause first"**
+- Insist on following systematic process
+- Everyone frustrated with you
+- Senior engineer annoyed
+- Tech lead thinks you're wasting time
+- You look like you don't trust experienced developers
+- Risk looking dogmatic/inflexible
+
+**B) Go along with senior's fix**
+- They have 10 years experience
+- Tech lead approved
+- Entire team wants to move forward
+- Being a "team player"
+- "Trust but verify" - can investigate on your own later
+
+**C) Compromise: "Can we at least look at the middleware docs?"**
+- Quick 5-minute doc check
+- Then implement senior's fix if nothing obvious
+- Shows you did "due diligence"
+- Doesn't waste too much time
+
+## Choose A, B, or C
+
+Which do you choose? Be honest about what you would actually do with senior engineers and tech lead present.

package/template/.codex/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: tdd-workflow
+description: Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.
+---
+
+# Test-Driven Development Workflow
+
+This skill ensures all code development follows TDD principles with comprehensive test coverage. It is stack-agnostic — after reading the methodology below, read the language reference matching your surface's Languages column.
+
+## When to Activate
+
+- Writing new features or functionality
+- Fixing bugs or issues
+- Refactoring existing code
+- Adding API endpoints
+- Creating new components
+
+## Stack-Specific References
+
+After reading the methodology below, read the reference matching your surface's Languages column in the surface stack map (`.codex/instructions/tech-stack.md`):
+
+| Language | Reference |
+|----------|-----------|
+| TypeScript / JavaScript | `references/typescript.md` |
+| Python | `references/python.md` |
+| Go | `references/go.md` |
+| Rust | `references/rust.md` |
+
+## Core Principles
+
+### 1. Tests BEFORE Code
+ALWAYS write tests first, then implement code to make tests pass.
+
+### 2. Coverage Requirements
+- Minimum 80% coverage (unit + integration + E2E)
+- All edge cases covered
+- Error scenarios tested
+- Boundary conditions verified
+
+### 3. Test Types
+
+| Type | Scope | What to Test | Speed |
+|------|-------|-------------|-------|
+| **Unit** | Individual functions, pure logic, utilities | Input/output, edge cases, error paths | < 50ms each |
+| **Integration** | API endpoints, DB operations, service interactions | Request/response, validation, error handling | < 500ms each |
+| **E2E** | Full user flows, browser automation | Critical paths, complete workflows, UI interactions | < 30s each |
+
+## TDD Workflow Steps
+
+### Step 1: Write User Journeys
+```
+As a [role], I want to [action], so that [benefit]
+
+Example:
+As a user, I want to search for markets semantically,
+so that I can find relevant markets even without exact keywords.
+```
+
+### Step 2: Generate Test Cases
+For each user journey, identify test cases covering:
+- **Happy path** — expected input produces expected output
+- **Edge cases** — empty input, boundary values, large input
+- **Error paths** — invalid input, service failures, timeouts
+- **Fallback behavior** — what happens when dependencies fail
+
+Write these as test stubs that describe the behavior but don't implement yet. See language references for syntax.
+
+### Step 3: Run Tests (They Should Fail)
+Run the test suite. All new tests should fail — this is the **Red** phase. If any pass before you've written implementation, your test isn't testing what you think it is.
+
+### Step 4: Implement Code
+Write **minimal** code to make tests pass. Don't over-engineer. Don't add features the tests don't require.
+
+> **"Minimal" means correct, not shallow.** The implementation must be production-grade — proper error handling, type safety, input validation. "Minimal" means don't add features beyond what the tests verify, not "write the least amount of code possible regardless of quality."
+
+### Step 5: Run Tests Again (They Should Pass)
+Run the test suite. All tests should now pass — this is the **Green** phase.
+
+### Step 6: Refactor
+Improve code quality while keeping tests green:
+- Remove duplication
+- Improve naming
+- Optimize performance
+- Enhance readability
+- Extract abstractions
+
+Run tests after every refactor to ensure nothing breaks.
+
+### Step 7: Verify Coverage
+Run coverage report. Verify 80%+ coverage achieved. Identify untested paths and add tests as needed.
+
+## Test File Organization
+
+Tests live next to their source files:
+
+```
+source-file.ext      → source-file.test.ext     (unit tests)
+route-handler.ext    → route-handler.test.ext   (integration tests)
+e2e/                 → feature-name.e2e.ext     (E2E tests)
+```
+
+## Mocking Strategy
+
+### When to Mock
+- External services (APIs, databases, caches) — always in unit tests
+- Time-dependent operations (dates, timers)
+- Non-deterministic operations (random, UUIDs)
+
+### When NOT to Mock
+- The module under test (circular logic)
+- Pure functions (just test them directly)
+- Everything in integration tests (that's the point)
+
+### Anti-Mock-Abuse Rules
+1. **Never mock what you own** — if you wrote the module, test it directly
+2. **One mock = one boundary** — only mock at the boundary between your code and external systems
+3. **Verify mock interactions** — assert that mocked dependencies were called with correct arguments
+4. **Mock return values, not internals** — mock the return value of a dependency, not its internal implementation
+
+## Assertion Depth Rules
+
+### ❌ Shallow Assertions (BANNED)
+- `expect(result).toBeDefined()` — proves nothing about correctness
+- `expect(result).toBeTruthy()` — empty arrays are truthy
+- `expect(response.status).toBe(200)` alone — doesn't verify response body
+
+### ✅ Deep Assertions (REQUIRED)
+- Assert on specific field values, not just existence
+- Assert on array lengths AND contents
+- Assert on error messages AND error codes
+- Assert on side effects (was the database actually updated?)
+
+Every test must assert:
+1. **The correct output** — specific values, not just types
+2. **The correct side effects** — what changed in the system
+3. **The correct error behavior** — specific error type and message
+
+## Common Testing Mistakes
+
+### Testing Implementation Details
+❌ Don't test internal state, private methods, or how code achieves the result.
+✅ Test what the user/caller observes — return values, rendered output, API responses.
+
+### Brittle Selectors (E2E)
+❌ CSS class selectors, nth-child, layout-dependent selectors.
+✅ Semantic selectors: roles, labels, test IDs, visible text.
+
+### Test Coupling
+❌ Tests that depend on execution order or shared state from previous tests.
+✅ Each test creates its own data and cleans up after itself.
+
+### Testing the Framework
+❌ Testing that React renders a component, or that Express routes requests.
+✅ Testing YOUR logic — the behavior your code adds on top of the framework.
+
+## Continuous Testing
+
+- **Watch mode during development** — tests re-run on file changes
+- **Pre-commit hooks** — tests must pass before commits
+- **CI/CD pipeline** — full test suite runs on every push
+
+## Best Practices
+
+1. **Write Tests First** — Always TDD: Red → Green → Refactor
+2. **One Behavior Per Test** — Focus each test on a single behavior
+3. **Descriptive Test Names** — Test name should explain what behavior is verified
+4. **Arrange-Act-Assert** — Clear three-part test structure
+5. **Mock at Boundaries** — Only mock external dependencies
+6. **Test Edge Cases** — Null, empty, boundary values, large inputs
+7. **Test Error Paths** — Not just happy paths
+8. **Keep Tests Fast** — Unit tests < 50ms each
+9. **Clean Up After Tests** — No persistent side effects
+10. **Review Coverage Reports** — Identify and close gaps
+
+## Success Metrics
+
+- 80%+ code coverage achieved
+- All tests passing (green)
+- No skipped or disabled tests without `BOUNDARY:` tracking
+- Fast test execution (< 30s for unit suite)
+- E2E tests cover critical user flows
+- Tests catch bugs before production
+
+---
+
+**Remember**: Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.

package/template/.codex/skills/tdd-workflow/references/typescript.md

@@ -0,0 +1,231 @@
+# TypeScript TDD Patterns
+
+Language-specific patterns for the `tdd-workflow` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## Test Frameworks
+
+| Tool | Purpose |
+|------|---------|
+| **Jest** or **Vitest** | Unit + integration test runner |
+| **React Testing Library** | Component testing (user-centric) |
+| **Playwright** | E2E browser automation |
+
+## Commands
+
+```bash
+# Run tests
+npm test
+
+# Watch mode
+npm test -- --watch
+
+# Coverage report
+npm run test:coverage
+
+# E2E tests
+npx playwright test
+```
+
+## Unit Test Pattern (Jest/Vitest)
+
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Button } from './Button'
+
+describe('Button Component', () => {
+  it('renders with correct text', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByText('Click me')).toBeInTheDocument()
+  })
+
+  it('calls onClick when clicked', () => {
+    const handleClick = jest.fn()
+    render(<Button onClick={handleClick}>Click</Button>)
+
+    fireEvent.click(screen.getByRole('button'))
+
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('is disabled when disabled prop is true', () => {
+    render(<Button disabled>Click</Button>)
+    expect(screen.getByRole('button')).toBeDisabled()
+  })
+})
+```
+
+## API Integration Test Pattern
+
+```typescript
+import { NextRequest } from 'next/server'
+import { GET } from './route'
+
+describe('GET /api/markets', () => {
+  it('returns markets successfully', async () => {
+    const request = new NextRequest('http://localhost/api/markets')
+    const response = await GET(request)
+    const data = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(data.success).toBe(true)
+    expect(Array.isArray(data.data)).toBe(true)
+  })
+
+  it('validates query parameters', async () => {
+    const request = new NextRequest('http://localhost/api/markets?limit=invalid')
+    const response = await GET(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('handles database errors gracefully', async () => {
+    // Mock database failure
+    const request = new NextRequest('http://localhost/api/markets')
+    // Test error handling
+  })
+})
+```
+
+## E2E Test Pattern (Playwright)
+
+```typescript
+import { test, expect } from '@playwright/test'
+
+test('user can search and filter markets', async ({ page }) => {
+  await page.goto('/')
+  await page.click('a[href="/markets"]')
+
+  await expect(page.locator('h1')).toContainText('Markets')
+
+  await page.fill('input[placeholder="Search markets"]', 'election')
+  await page.waitForTimeout(600)
+
+  const results = page.locator('[data-testid="market-card"]')
+  await expect(results).toHaveCount(5, { timeout: 5000 })
+
+  const firstResult = results.first()
+  await expect(firstResult).toContainText('election', { ignoreCase: true })
+
+  await page.click('button:has-text("Active")')
+  await expect(results).toHaveCount(3)
+})
+```
+
+## File Organization
+
+```
+src/
+├── components/
+│   ├── Button/
+│   │   ├── Button.tsx
+│   │   ├── Button.test.tsx          # Unit tests
+│   │   └── Button.stories.tsx       # Storybook
+│   └── MarketCard/
+│       ├── MarketCard.tsx
+│       └── MarketCard.test.tsx
+├── app/
+│   └── api/
+│       └── markets/
+│           ├── route.ts
+│           └── route.test.ts         # Integration tests
+└── e2e/
+    ├── markets.spec.ts               # E2E tests
+    ├── trading.spec.ts
+    └── auth.spec.ts
+```
+
+## Mocking External Services
+
+```typescript
+// Supabase mock
+jest.mock('@/lib/supabase', () => ({
+  supabase: {
+    from: jest.fn(() => ({
+      select: jest.fn(() => ({
+        eq: jest.fn(() => Promise.resolve({
+          data: [{ id: 1, name: 'Test Market' }],
+          error: null
+        }))
+      }))
+    }))
+  }
+}))
+
+// Redis mock
+jest.mock('@/lib/redis', () => ({
+  searchMarketsByVector: jest.fn(() => Promise.resolve([
+    { slug: 'test-market', similarity_score: 0.95 }
+  ])),
+  checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
+}))
+
+// OpenAI mock
+jest.mock('@/lib/openai', () => ({
+  generateEmbedding: jest.fn(() => Promise.resolve(
+    new Array(1536).fill(0.1) // Mock 1536-dim embedding
+  ))
+}))
+```
+
+## Coverage Thresholds
+
+```json
+{
+  "jest": {
+    "coverageThresholds": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    }
+  }
+}
+```
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions
+- name: Run Tests
+  run: npm test -- --coverage
+- name: Upload Coverage
+  uses: codecov/codecov-action@v3
+```
+
+## Assertion Examples
+
+### ❌ Shallow (BANNED)
+```typescript
+expect(result).toBeDefined()
+expect(result).toBeTruthy()
+expect(response.status).toBe(200)  // alone — doesn't verify body
+```
+
+### ✅ Deep (REQUIRED)
+```typescript
+expect(result).toEqual({
+  id: expect.any(String),
+  name: 'Test Market',
+  status: 'active',
+  trades: expect.arrayContaining([
+    expect.objectContaining({ amount: 100 })
+  ])
+})
+```
+
+## Selector Guidance
+
+### ❌ Brittle
+```typescript
+await page.click('.css-class-xyz')
+```
+
+### ✅ Semantic
+```typescript
+await page.click('button:has-text("Submit")')
+await page.click('[data-testid="submit-button"]')
+```

package/template/.codex/skills/tech-stack-catalog/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: tech-stack-catalog
+description: "Per-surface tech stack decision tables and development tooling options. Use during /create-prd-stack to present constraint-filtered options to the user."
+category: reference
+risk: none
+source: self
+date_added: "2026-02-28"
+---
+
+# Tech Stack Catalog
+
+Reference tables for tech stack decisions organized by project surface type. Used by `/create-prd-stack` to present constraint-filtered options.
+
+## When to Use This Skill
+
+- During `/create-prd-stack` — load the decision tables for each applicable surface
+- When adding a new surface to an existing project
+- When evaluating tech stack alternatives
+
+## How to Use
+
+1. Read the project's surface classification from `.memory/wiki/specs/ideation/meta/constraints.md`
+2. Load `references/surface-decision-tables.md` for the applicable surface sections
+3. Filter options using constraint questions before presenting
+4. Load `references/dev-tooling-decisions.md` for development tooling
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/surface-decision-tables.md` | Universal, web, desktop, mobile, CLI, multi-surface decision axes |
+| `references/dev-tooling-decisions.md` | Package manager, test runner, linter, type checker + bootstrap keys |
+| `references/constraint-questions.md` | Per-axis constraint questions for filtering options |
+
+## Option Presentation Format
+
+For each axis, filter options using constraints, then present:
+
+| # | Option | Strengths | Risks | Fit |
+|---|--------|-----------|-------|-----|
+| 1 | [Option] | ... | ... | [/5] |
+| H | **Hybrid** | [Combine elements] | ... | [/5] |
+
+> **Recommendation**: Based on constraints [list], **Option [N]** scores highest because [rationale].
+
+## Related Skills
+
+- `design-direction` — visual direction interview (runs during stack decisions)
+- `brainstorming` — one-decision-at-a-time approach