stemedb/applications/aphoria/dogfood/dbpool

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:

./scripts/validate-setup.sh

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

Then read the execution guide:

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