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):**
```bash
./create-claims.sh  # 300+ line bash script
```

**New approach (modern):**
```bash
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
```bash
aphoria claims import claims-template.toml --dry-run
```

### Validate Format
```bash
aphoria claims import claims-template.toml --validate-only
```

### Import with Merge Strategy
```bash
aphoria claims import claims-template.toml --merge skip_existing
```

### JSON Output for Scripting
```bash
aphoria claims import claims-template.toml --format json
```

---

## Day 1 Workflow (Updated)

**Option 1: Interactive (LLM-driven)**
```bash
/aphoria-suggest --corpus httpclient,dbpool --domain msgqueue
/aphoria-claims  # Author claims interactively
```

**Option 2: Batch Import (Fast)**
```bash
# 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**
```bash
# 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/getting-started/` - 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:**
```bash
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:**
   ```bash
   aphoria claims list --format json > existing-claims.json
   ```

2. **Generate template:**
   ```bash
   aphoria claims import --template > claims-template.toml
   ```

3. **Migrate claims to TOML:**
   - Copy claim structure from JSON
   - Follow TOML template format

4. **Test import:**
   ```bash
   aphoria claims import claims-template.toml --validate-only
   aphoria claims import claims-template.toml --dry-run
   ```

5. **Replace shell script:**
   ```bash
   rm create-claims.sh
   git add claims-template.toml
   ```

---

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