# Database Connection Pool (`dbpool`) - Aphoria Dogfood Exercise

**Status:** 🎯 **READY FOR NEXT TEAM RUN** (Reset: 2026-02-09)

## What This Is

A 5-day dogfood exercise to demonstrate Aphoria's code-level truth linting by:
1. Creating authoritative claims about database connection pools
2. Writing intentionally violating code
3. Using Aphoria to detect all violations
4. Fixing violations incrementally
5. Documenting the success story

## Quick Start

**Before you begin, run the pre-flight validator:**

```bash
./scripts/validate-setup.sh
```

This checks all prerequisites and shows you exactly what to fix.

**Then read the execution guide:**

```bash
cat CHECKLIST.md  # Day-by-day execution checklist with templates
cat CLAUDE.md     # Development commands and architecture
cat plan.md       # Complete 5-day plan with detailed schedule
```

## What's Been Reset

This directory has been cleaned up from a previous run:

### ✅ Kept (Ready to Use)
- **Documentation** (updated based on team evaluation)
  - `CHECKLIST.md` - Fixed Day 1 structure, added 27 claim checkboxes, practice bridge
  - `CLAUDE.md` - Development commands, architecture reference
  - `plan.md` - Complete 5-day schedule
  - `docs/claim-extraction-example.md` - Complete walkthrough with worked examples
  - `docs/flywheel-setup.md` - **NEW:** Flywheel configuration guide
  - `docs/sources/` - Authority source documents (HikariCP, PostgreSQL, OWASP)

- **Configuration**
  - `.aphoria/config.toml` - Pre-configured with flywheel settings (persistent mode, aggregation enabled)
  - `.claude/` - Claude Code skills and configuration

- **Tools**
  - `scripts/validate-setup.sh` - Pre-flight validation script

- **Previous Run Analysis** (for reference)
  - `eval/` - Evaluation reports from 2026-02-09 run documenting what went wrong

### ❌ Removed (Will Be Created During Exercise)
- `src/` - Implementation code (Day 2)
- `tests/` - Test suite (Day 2)
- `Cargo.toml` - Rust manifest (Day 2)
- `scan-results-*.json` - Scan outputs (Day 3+)
- `IMPLEMENTATION-SUMMARY.md` - Moved to `eval/`

## Documentation Improvements

Based on team evaluation (see `eval/EVALUATION-REPORT-2026-02-09.md`), the following fixes were applied:

### 🔧 What Was Fixed

1. **Day 1 Heading Clarity** - Changed from "Information Needed" to "Create 25-30 Claims"
2. **Success Criteria Visible** - Added verification command at top of Day 1
3. **27 Checkbox Items** - All claims now have checkboxes (vs prose that was skipped)
4. **Practice Bridge** - Added 3 practice claims after reading example
5. **Step Numbers** - Clear Step 1, 2, 3, 4 structure for Day 1
6. **Flywheel Documentation** - New `docs/flywheel-setup.md` guide
7. **Day 3 Flywheel Setup** - Added critical configuration section before scanning

### 📊 Expected Impact

- **Previous run:** Team created 0/27 claims, thought Day 1 was 90% complete
- **Expected now:** 85-90% completion rate with clear checkboxes and deliverables

## Day-by-Day Overview

| Day | Focus | Key Deliverable | Time |
|-----|-------|-----------------|------|
| **Day 1** | Corpus Building | 25-30 claims created via CLI | 4-6 hours |
| **Day 2** | Implementation | Working code with 7-8 intentional violations | 4-5 hours |
| **Day 3** | Scanning | Initial scan showing all violations | 2-3 hours |
| **Day 4** | Remediation | Progressive fixes with re-scans | 4-5 hours |
| **Day 5** | Documentation | Success story, demo materials | 3-4 hours |

**Total:** ~20 hours (5 days at 4 hours/day)

## Success Metrics

After completion, you should have:

- ✅ 25-30 claims in corpus database
- ✅ 7-8 violations detected in initial scan
- ✅ 100% detection accuracy (no false positives/negatives)
- ✅ Scan performance ≤0.3s (ephemeral mode)
- ✅ Progressive fixes showing improvement
- ✅ Final clean scan (0 violations)
- ✅ Compelling success story
- ✅ Live demo materials

## Prerequisites

Run `./scripts/validate-setup.sh` to verify:

1. Aphoria CLI installed (`aphoria --version`)
2. StemeDB API running on `:18180`
3. Corpus database accessible at `~/.aphoria/corpus-db/`
4. Corpus API returns data
5. `jq` JSON processor installed
6. Rust toolchain available
7. Aphoria extractors detect patterns

## Important Notes

1. **Read `docs/claim-extraction-example.md` first** (Day 1)
   - 15-20 minutes to understand claim extraction
   - Prevents creating garbage "observations" instead of real claims

2. **Configure flywheel before Day 3** (see `docs/flywheel-setup.md`)
   - Switch from ephemeral to persistent mode
   - Enable pattern aggregation
   - Demonstrates learning capability

3. **Intentional violations are educational** (Day 2)
   - You're deliberately writing bad code to test detection
   - This is normal and expected for dogfooding

4. **Save all scan results** (Day 3-4)
   - `scan-results-v1.json` through `scan-results-v6.json`
   - Needed for before/after evidence in Day 5 documentation

## Getting Help

- **Aphoria CLI issues:** Check `applications/aphoria/README.md`
- **API issues:** Verify `http://localhost:18180/health`
- **Corpus issues:** Query `curl 'http://localhost:18180/v1/aphoria/corpus'`
- **Common issues:** See `CHECKLIST.md` troubleshooting section

## What Makes This Different

This dogfood exercise demonstrates:

- **Real authority sources** (HikariCP, PostgreSQL, OWASP)
- **Verifiable violations** (connection exhaustion, credential exposure, validation gaps)
- **Prevented incidents** (estimated $50K+ in production outages)
- **Production-ready output** (final code is genuinely deployable)

## Next Steps

1. **Run pre-flight validation:** `./scripts/validate-setup.sh`
2. **Read Day 1 checklist:** `cat CHECKLIST.md | head -300`
3. **Start with claim extraction example:** `cat docs/claim-extraction-example.md`
4. **Begin Day 1:** Follow CHECKLIST.md to create 25-30 claims

---

**Last Reset:** 2026-02-09 (after team evaluation)
**Documentation Version:** v2 (includes fixes from evaluation gaps)
**Ready for:** Fresh team run with improved documentation