stemedb/applications/aphoria/dogfood/msgqueue/SETUP-NOTES.md

Message Queue Dogfood Setup - Migration Notes

Date: 2026-02-10 Status: ✅ Setup Complete (Modern CLI Pattern)

---

What Changed from Original Plan

✅ Migrated from Shell Script to CLI Import

Old approach (deprecated):

./create-claims.sh  # 300+ line bash script

New approach (modern):

aphoria claims import claims-template.toml  # Native CLI command

Why?

• CLI added claims import subcommand with bulk support (commit 7facac0)
• TOML format is more maintainable than bash scripts
• Better validation, preview, and error reporting
• Consistent with other Aphoria workflows

---

Files Created

msgqueue/
├── README.md                    ✅ Overview with hypothesis
├── plan.md                      ✅ 5-day workflow (updated to use import)
├── .aphoria/
│   ├── config.toml              ✅ Persistent mode, corpus enabled
│   └── claims.toml              ✅ Empty (fill on Day 1)
├── docs/
│   └── sources/                 ✅ Authority source templates (3 files)
│       ├── amqp-spec.md
│       ├── rabbitmq-docs.md
│       └── lapin-library.md
├── src/
│   └── .gitkeep                 ✅ Placeholder
├── claims-template.toml         ✅ 22 claims ready to import
└── SETUP-NOTES.md               ✅ This file

Removed:

• ❌ create-claims.sh (replaced by claims-template.toml)

---

CLI Import Features Used

Preview Before Import

aphoria claims import claims-template.toml --dry-run

Validate Format

aphoria claims import claims-template.toml --validate-only

Import with Merge Strategy

aphoria claims import claims-template.toml --merge skip_existing

JSON Output for Scripting

aphoria claims import claims-template.toml --format json

---

Day 1 Workflow (Updated)

Option 1: Interactive (LLM-driven)

/aphoria-suggest --corpus httpclient,dbpool --domain msgqueue
/aphoria-claims  # Author claims interactively

Option 2: Batch Import (Fast)

# Preview first
aphoria claims import claims-template.toml --dry-run

# Import all 22 claims at once
aphoria claims import claims-template.toml

# Verify
cat .aphoria/claims.toml

Option 3: Hybrid

# Import base claims
aphoria claims import claims-template.toml

# Then use LLM to refine or add more
/aphoria-claims

---

Pattern Reuse Breakdown

From httpclient (6 patterns):

1. timeout → consumer/timeout
2. tls/certificate_validation → tls/certificate_validation
3. metrics/enabled → metrics/enabled
4. retry/max_attempts → retry/max_attempts
5. retry/backoff_strategy → retry/backoff_strategy
6. async/runtime → async/runtime

From dbpool (5 patterns):

7. max_connections → connection/max_connections
8. connection_lifecycle → connection/lifecycle
9. cleanup → connection/cleanup
10. idle_timeout → connection/idle_timeout
11. pool_size → connection/pool_size (implicit via max_connections)

New for msgqueue (11 patterns):

12. consumer/prefetch_count
13. consumer/ack_mode
14. consumer/ack_timeout
15. queue/max_size
16. consumer/backpressure_strategy
17. connection/heartbeat_interval
18. consumer/requeue_limit
19. queue/durable
20. consumer/exclusive
21. connection/recovery_strategy
22. consumer/dead_letter_queue

Total: 22 claims (11 reused = 50% reuse rate)

---

Documentation Updates Needed

✅ Already Updated:

• msgqueue/plan.md - Uses aphoria claims import
• msgqueue/README.md - References TOML template
• .claude/skills/aphoria-dogfood/SKILL.md - Global pattern updated

⚠️ May Need Updates:

• applications/aphoria/dogfood/httpclient/ - Still uses shell script?
• applications/aphoria/docs/guides/ - Check if mentions shell scripts
• Other existing dogfood exercises

---

Next Steps

1. Day 1: Import claims from template or use /aphoria-suggest
2. Day 2: Implement Rust consumer with 8 violations
3. Day 3: Scan and verify detection
4. Day 4: Progressive fixes
5. Day 5: Comprehensive report

Start here:

cd /home/jml/Workspace/stemedb/applications/aphoria/dogfood/msgqueue
aphoria claims import claims-template.toml --dry-run

---

Benefits of TOML Import

Feature	Shell Script	TOML Import
Validation	None (bash executes)	✅ Schema validation before import
Preview	Must read source	✅ --dry-run shows what will change
Error handling	Script fails mid-way	✅ Atomic import (all or nothing)
Maintainability	300+ lines bash	✅ 300 lines clean TOML
Merge strategies	Manual deduplication	✅ --merge handles conflicts
Output formats	Plain text	✅ Table, JSON for scripting
Extensibility	Edit bash script	✅ Edit TOML template

---

Migration Pattern for Other Exercises

If you have other dogfood exercises using shell scripts:

1. Export existing claims:

   aphoria claims list --format json > existing-claims.json
   

2. Generate template:

   aphoria claims import --template > claims-template.toml
   

3. Migrate claims to TOML:

   • Copy claim structure from JSON
   • Follow TOML template format

4. Test import:

   aphoria claims import claims-template.toml --validate-only
   aphoria claims import claims-template.toml --dry-run
   

5. Replace shell script:

   rm create-claims.sh
   git add claims-template.toml
   

---

This pattern is now the standard for all new dogfood exercises.