stemedb/applications/aphoria/dogfood/SYSTEMATIC-FIXES-2026-02-10.md

Systematic Fixes: Invalid Comparison Modes Across Dogfood Exercises

Date: 2026-02-10 Issue: Invalid ComparisonMode values (greater_than, less_than, in_range, max_value, min_value) used throughout dogfood exercises Root Cause: Template creation assumed numeric comparison operators exist in Aphoria Valid Modes: equals, not_equals, present, absent, contains, not_contains

---

Summary of Audit

✅ msgqueue - FIXED

• claims-template.toml - ✅ Fixed with valid comparison modes
• FIXES-APPLIED.md - ✅ Documented the fix
• .aphoria/claims.toml - ✅ Contains valid claims

❌ dbpool - BROKEN (Extensive)

• .aphoria/claims.toml - ❌ HAS ACTIVE INVALID CLAIMS
• plan.md - ❌ Shows invalid predicates in tables
• CHECKLIST.md - ❌ Templates teach invalid modes
• CLAUDE.md - ❌ Documentation references invalid modes
• claim-extraction-example.md - ❌ Examples use invalid modes
• .aphoria/config.toml - ❌ Comments reference invalid modes
• src/config.rs - ❌ Code comments reference invalid modes
• docs/multi-project-setup.md - ❌ Guide shows invalid modes
• Historical/archived docs - ⚠️ Contain invalid modes (leave as-is, historical record)

✅ httpclient - UNKNOWN

• No invalid modes found in active files
• User reported immediate failure, but no template files exist

✅ ~/.claude/skills/ - CLEAN

• No invalid comparison modes found

✅ applications/aphoria/docs/ - CLEAN

• No invalid comparison modes found

---

Critical Files to Fix

1. dbpool/.aphoria/claims.toml (ACTIVE CLAIMS - HIGHEST PRIORITY)

Location: /home/jml/Workspace/stemedb/applications/aphoria/dogfood/dbpool/.aphoria/claims.toml

Problem: Line 256 has predicate = "min_value" which is INVALID.

Impact: CRITICAL - This is the active claims file. Aphoria will fail to parse it.

Fix Required:

# WRONG:
[[claim]]
id = "dbpool-006"
concept_path = "dbpool/min_connections"
predicate = "min_value"
value = 2
comparison = "equals"

# CORRECT:
[[claim]]
id = "dbpool-006"
concept_path = "dbpool/min_connections"
predicate = "minimum"
value = 2
comparison = "equals"

Pattern: For numeric constraints, encode the constraint in the predicate name:

• ❌ predicate = "min_value" → ✅ predicate = "minimum"
• ❌ predicate = "max_value" → ✅ predicate = "maximum"
• Or use predicate = "bounded" with value = true and document range in invariant

2. dbpool/plan.md (DOCUMENTATION - HIGH PRIORITY)

Location: /home/jml/Workspace/stemedb/applications/aphoria/dogfood/dbpool/plan.md

Problems:

• Lines 111-113, 118: Tables show max_value, min_value as predicates
• Lines 189, 197: Examples reference these invalid modes

Fix Required: Update all tables to show valid patterns:

# WRONG:
| `dbpool/min_connections` | `min_value` | `2` | HikariCP | 2 |

# CORRECT:
| `dbpool/min_connections` | `minimum` | `2` | HikariCP | 2 |
# OR
| `dbpool/min_connections/minimum` | `value` | `2` | HikariCP | 2 |
# OR (preferred - matches msgqueue pattern)
| `dbpool/min_connections` | `bounded` | `true` | HikariCP | 2 |
# (with invariant: "min_connections MUST be >= 2")

3. dbpool/CHECKLIST.md (TEMPLATES - HIGH PRIORITY)

Location: /home/jml/Workspace/stemedb/applications/aphoria/dogfood/dbpool/CHECKLIST.md

Problems:

• Line 409: Template command shows max_value|min_value as options
• Lines 468, 498-499, 504, 506, 630, 636: Examples use invalid modes

Fix Required: Update template to show only valid predicates:

# WRONG:
aphoria corpus create \
  --predicate "{required|recommended|max_value|min_value}" \

# CORRECT:
aphoria corpus create \
  --predicate "{required|recommended|bounded|version}" \

4. dbpool/CLAUDE.md (GUIDANCE - HIGH PRIORITY)

Location: /home/jml/Workspace/stemedb/applications/aphoria/dogfood/dbpool/CLAUDE.md

Problems:

• Line 71: Template shows invalid predicates
• Lines 178-179: Table references invalid modes

Fix Required: Same as CHECKLIST.md - update templates to valid modes.

5. dbpool/docs/claim-extraction-example.md (EXAMPLES - HIGH PRIORITY)

Location: /home/jml/Workspace/stemedb/applications/aphoria/dogfood/dbpool/docs/claim-extraction-example.md

Problems:

• Lines 201, 222: Examples create claims with max_value, min_value

Fix Required: Rewrite examples to use valid comparison modes with proper encoding:

# WRONG:
aphoria corpus create \
  --subject "dbpool/connection_timeout" \
  --predicate "max_value" \
  --value "30"

# CORRECT (Option 1 - encode in predicate):
aphoria corpus create \
  --subject "dbpool/connection_timeout" \
  --predicate "maximum" \
  --value 30 \
  --comparison "equals"

# CORRECT (Option 2 - encode in concept_path):
aphoria corpus create \
  --subject "dbpool/connection_timeout/maximum" \
  --predicate "value" \
  --value 30 \
  --comparison "equals"

# CORRECT (Option 3 - msgqueue pattern):
aphoria corpus create \
  --subject "dbpool/connection_timeout" \
  --predicate "excessive" \
  --value 30 \
  --comparison "not_equals" \
  --invariant "connection_timeout MUST NOT exceed 30s (HikariCP)"

6. dbpool/.aphoria/config.toml (COMMENTS - MEDIUM PRIORITY)

Location: /home/jml/Workspace/stemedb/applications/aphoria/dogfood/dbpool/.aphoria/config.toml

Problems:

• Lines 107, 123, 133: Comments reference max_value, min_value

Fix Required: Update comments to reflect actual valid predicates.

7. dbpool/src/config.rs (CODE COMMENTS - LOW PRIORITY)

Location: /home/jml/Workspace/stemedb/applications/aphoria/dogfood/dbpool/src/config.rs

Problems:

• Lines 45, 57: Code comments reference invalid modes

Fix Required: Update comments to match actual claim structure after fixes.

8. dbpool/docs/multi-project-setup.md (GUIDE - MEDIUM PRIORITY)

Location: /home/jml/Workspace/stemedb/applications/aphoria/dogfood/dbpool/docs/multi-project-setup.md

Problems:

• Lines 53, 119: Examples show max_value predicate

Fix Required: Update examples to valid predicates.

---

Files That DON'T Need Fixes

Historical/Archived Documents (Keep as-is)

• dbpool/eval-archive-2026-02-09/ - Historical evaluation, keep for record
• dbpool/DAY2-COMPLETE.md - Historical completion report
• dbpool/verify-results-v1.json - Historical scan results
• msgqueue/FIXES-APPLIED.md - Already documents the issue

Rationale: These are historical artifacts showing what happened on specific dates. Changing them would falsify the historical record.

---

Fix Strategy

Phase 1: Fix Active Claims (CRITICAL - Do First)

1. ✅ msgqueue/.aphoria/claims.toml - Already fixed
2. ❌ dbpool/.aphoria/claims.toml - Fix immediately

Phase 2: Fix Documentation (HIGH - Prevent Recurrence)

3. dbpool/plan.md - Update tables
4. dbpool/CHECKLIST.md - Update templates
5. dbpool/CLAUDE.md - Update guidance
6. dbpool/docs/claim-extraction-example.md - Update examples

Phase 3: Fix Auxiliary Files (MEDIUM - Consistency)

7. dbpool/.aphoria/config.toml - Update comments
8. dbpool/docs/multi-project-setup.md - Update guide

Phase 4: Fix Code Comments (LOW - Polish)

9. dbpool/src/config.rs - Update comments

---

Validation After Fixes

Test 1: Validate Claims Files

# msgqueue
cd applications/aphoria/dogfood/msgqueue
aphoria claims import claims-template.toml --validate-only
# Expected: ✓ Validation passed

# dbpool
cd applications/aphoria/dogfood/dbpool
aphoria claims list --format json | jq '.claims[] | .predicate' | sort -u
# Expected: Only valid predicates (required, recommended, bounded, etc.)

Test 2: Search for Remaining Invalid Modes

cd applications/aphoria/dogfood
grep -r "greater_than\|less_than\|in_range\|max_value\|min_value" . \
  --exclude-dir=eval-archive-2026-02-09 \
  --exclude="*FIXES-APPLIED.md" \
  --exclude="*SYSTEMATIC-FIXES*.md" \
  --exclude="DAY2-COMPLETE.md" \
  --exclude="verify-results-v1.json"

# Expected: Only matches in historical/archived files

Test 3: Verify No Broken Templates

# Check that all templates use only valid comparison modes
grep -r "comparison.*=" applications/aphoria/dogfood/ \
  --include="*.toml" \
  --include="*.md" \
  | grep -v "equals\|not_equals\|present\|absent\|contains\|not_contains" \
  | grep -v "eval-archive"

# Expected: No matches (or only in historical files)

---

Prevention: Add to Skill Templates

Update ~/.claude/skills/aphoria-dogfood/SKILL.md to include warning:

## CRITICAL: Valid ComparisonMode Values

Aphoria's ComparisonMode enum ONLY supports:
- ✅ `equals`
- ✅ `not_equals`
- ✅ `present`
- ✅ `absent`
- ✅ `contains`
- ✅ `not_contains`

❌ INVALID (do not use):
- ❌ `greater_than`
- ❌ `less_than`
- ❌ `in_range`
- ❌ `max_value`
- ❌ `min_value`

**For numeric constraints:**
Encode the constraint in the predicate or concept_path:

Example:
```toml
# WRONG:
predicate = "max_value"
value = 30
comparison = "greater_than"  # INVALID

# CORRECT (Option 1):
predicate = "maximum"
value = 30
comparison = "equals"

# CORRECT (Option 2):
concept_path = "dbpool/connection_timeout/maximum"
predicate = "value"
value = 30
comparison = "equals"

# CORRECT (Option 3 - msgqueue pattern):
predicate = "excessive"
value = 30
comparison = "not_equals"

---

## Summary

### What Was Wrong
- **msgqueue:** Template used invalid comparison modes (fixed)
- **dbpool:** Extensive use of invalid predicates throughout documentation and active claims file
- **Root cause:** Template creation assumed numeric operators existed

### What's Fixed
- ✅ msgqueue claims template
- ✅ msgqueue documentation

### What's NOT Fixed
- ❌ dbpool active claims file (.aphoria/claims.toml)
- ❌ dbpool documentation (plan, checklist, CLAUDE.md)
- ❌ dbpool examples and guides

### Next Steps
1. Fix dbpool/.aphoria/claims.toml immediately (CRITICAL)
2. Fix all dbpool documentation systematically
3. Add validation to aphoria-dogfood skill to prevent recurrence
4. Consider adding a `--validate-claims` command to Aphoria CLI

### User Question Answered
> "did you fix things systemtically? our ~/.claude/**/*aphoria skills and our docs?"

**Answer:** NO
- ✅ ~/.claude/skills/ are clean (no invalid modes found)
- ✅ applications/aphoria/docs/ are clean
- ❌ dbpool dogfood is BROKEN extensively
- ✅ msgqueue dogfood is FIXED

**Action required:** Systematic fix of dbpool dogfood exercise following this report.