stemedb/applications/aphoria/dogfood/msgqueue/DAY3-READY.md

Day 3 Ready - Fresh Start with New Documentation

Date: 2026-02-11 Status: Ready for Day 3 validation test Purpose: Test new documentation fixes for extractor creation

---

Pre-Day 3 State

✅ Day 1 Complete: 22 claims authored in .aphoria/claims.toml ✅ Day 2 Complete: 8 violations embedded in src/ with inline markers ✅ Day 3 Reset: All previous Day 3 attempts removed (clean slate)

---

What Was Reset

Removed:

• All scan results (scan-v1.json, scan-v2.json, etc.)
• All scan reports (SCAN-v1.md, etc.)
• Previous DAY3-SUMMARY.md (from failed attempts)
• Previous DAY3-READY.md
• .aphoria/extractors/ directory
• All declarative extractors from .aphoria/config.toml

Kept:

• .aphoria/claims.toml (22 claims from Day 1)
• src/ code with 8 violations (Day 2)
• DAY1-SUMMARY.md and DAY2-SUMMARY.md
• Claims template and documentation

---

Day 3 Task: Validate New Documentation

Goal: Follow the new documentation to create extractors and achieve 100% detection rate.

Target Time: 30 minutes (vs 70 minutes in previous attempts) Target Detection Rate: 100% (8/8 violations detected) Success Criteria: Zero trial-and-error, all guidance from docs

---

New Documentation to Use

Primary References

1. Declarative Extractors Reference

   • File: ../../docs/extractors/declarative-extractors.md
   • What it covers:
     • Complete field reference (name, pattern, languages, subject, predicate, value)
     • CRITICAL: subject field must EXACTLY match claim's concept_path
     • Validation workflow (check before scanning)
     • Debugging 0% detection (if it happens)
     • Common mistakes with fixes

2. Worked Example

   • File: ../../docs/examples/extractors/timeout-zero-example.md
   • What it shows:
     • Complete flow: code → extractor → claim → conflict
     • Exact TOML format to copy
     • How path alignment works

3. Updated Day 3 Plan

   • File: plan.md (Day 3 section)
   • What's new:
     • Manual declarative extractor format (Step 3)
     • Validation workflow before scanning (Step 3)
     • Debug workflow for 0% detection (Step 4)

4. Common Mistakes Guide

   • File: ../../docs/dogfooding-common-mistakes.md
   • What it covers:
     • Mistake #1: Skipping extractor creation entirely
     • Mistake #2: Creating extractors with wrong subject format (NEW)
     • How to verify correct execution

---

Day 3 Workflow (Follow plan.md)

Phase 1: Pre-Flight Check (5 min)

# Verify code compiles
cargo check

# Verify inline markers present
grep -r "@aphoria:claim" src/ | wc -l
# Expected: 8 markers

---

Phase 2: Baseline Scan (15 min)

aphoria scan --format json > scan-v1.json
aphoria scan --format markdown > scan-v1.md

Expected: 0-20% detection rate (normal for new domain without extractors)

Action: Analyze which violations were missed.

---

Phase 3: Create Extractors (30 min) [CRITICAL]

Follow: plan.md Day 3 Step 3 (updated with manual format)

Key steps:

1. Read the reference docs:

   • ../../docs/extractors/declarative-extractors.md (field reference)
   • ../../docs/examples/extractors/timeout-zero-example.md (example)

2. For each violation, add extractor to .aphoria/config.toml:

   [[extractors.declarative]]
   name = "descriptive_name"
   pattern = 'regex_matching_code'
   languages = ["rust"]
   
   [extractors.declarative.claim]
   subject = "FULL_CLAIM_CONCEPT_PATH"  # ← Copy from claim EXACTLY
   predicate = "claim_predicate"
   value = violation_value
   confidence = 0.95
   

3. CRITICAL: Find claim's concept_path and copy EXACTLY:

   # Find claim concept_path
   grep "id = \"msgqueue-015\"" -A 2 .aphoria/claims.toml
   # Output shows: concept_path = "msgqueue/queue/max_size"
   
   # Copy this EXACTLY into extractor subject
   subject = "msgqueue/queue/max_size"  # ✅ CORRECT
   

   Common mistake:

   subject = "queue/max_size"  # ❌ WRONG (missing msgqueue/ prefix)
   

4. Validate BEFORE scanning:

   # Check all subjects match claim concept_paths
   grep "subject =" .aphoria/config.toml
   grep "concept_path =" .aphoria/claims.toml
   # Subjects should be subset of concept_paths
   
   # Test patterns match code
   grep -rE 'max_queue_size:\s*None' src/
   # Should find the violation line
   

---

Phase 4: Verification Scan (15 min)

aphoria scan --format json > scan-v2.json
aphoria scan --format markdown > scan-v2.md

Expected: ≥90% detection rate (8/8 or 7/8 violations detected)

If still 0% detection:

Follow debug workflow in plan.md Day 3 Step 4:

# Step 1: Check if observations were created
jq '.observations | length' scan-v2.json
# Expected: > 0

# Step 2: Compare observation paths vs claim paths
jq '.observations[].concept_path' scan-v2.json | sort -u
grep "concept_path =" .aphoria/claims.toml | cut -d'"' -f2 | sort -u
# Check for mismatches (missing prefix, etc.)

Common issue: Extractor subject doesn't match claim concept_path. Fix: Update subject to use full path, re-scan.

---

Phase 5: Documentation (15 min)

Create DAY3-SUMMARY.md with:

## Metrics

| Metric | Target | Actual | Delta |
|--------|--------|--------|-------|
| Detection (v1) | N/A | X/8 (X%) | Baseline |
| Extractors created | 8 | 8 | ✅ |
| Detection (v2) | ≥90% | 8/8 (100%) | ✅ +100% |
| Time spent | ≤30 min | Y min | {+/-} |

## What Worked

- Declarative-extractors.md provided clear format reference
- Validation workflow caught subject mismatches before scanning
- Debug workflow helped fix 0% detection (if needed)
- Time saved: Z minutes vs 70 min in previous attempts

## What Broke

(None expected with new docs)

## Documentation Quality

- Declarative extractor reference: {rating}/5
- Worked example clarity: {rating}/5
- Validation workflow usefulness: {rating}/5
- Debug workflow usefulness: {rating}/5

---

Success Criteria

After Day 3 completion, verify:

• 8 extractors created in .aphoria/config.toml
• All extractor subjects match claim concept_paths EXACTLY
• scan-v2.json shows ≥90% detection (8/8 or 7/8)
• DAY3-SUMMARY.md exists with metrics
• Time spent ≤30 minutes
• Zero trial-and-error (all guidance from docs)

Evidence check:

# Count extractors
grep -c "^\[\[extractors.declarative\]\]" .aphoria/config.toml
# Expected: 8

# Check detection improvement
jq '.summary.claims_conflict' scan-v1.json  # Should be low (0-2)
jq '.summary.claims_conflict' scan-v2.json  # Should be high (7-8)

---

Expected Violations

These 8 violations should be detected after extractor creation:

1. timeout=0 (src/config.rs:20)

   • Claim: msgqueue-001
   • Pattern: timeout:\s*Duration::from_secs\(0\)

2. verify_certificates=false (src/config.rs:68)

   • Claim: msgqueue-002
   • Pattern: verify_certificates:\s*false

3. max_connections=None (src/connection.rs:15)

   • Claim: msgqueue-003
   • Pattern: max_connections:\s*None

4. blocking in async fn (src/processor.rs:87)

   • Claim: msgqueue-009
   • Pattern: std::thread::sleep

5. prefetch_count=u16::MAX (src/consumer.rs:33)

   • Claim: msgqueue-012
   • Pattern: prefetch_count:\s*u16::MAX

6. ack_mode=AutoAck (src/consumer.rs:56)

   • Claim: msgqueue-013
   • Pattern: ack_mode:\s*AckMode::AutoAck

7. max_queue_size=None (src/config.rs:45)

   • Claim: msgqueue-015
   • Pattern: max_queue_size:\s*None

8. max_requeue_count=None (src/consumer.rs:65)

   • Claim: msgqueue-018
   • Pattern: max_requeue_count:\s*None

---

Tips for Success

1. Read the docs FIRST - Don't skip declarative-extractors.md
2. Copy concept_path EXACTLY - This is the #1 mistake
3. Validate before scanning - Use grep to check alignment
4. Test patterns with grep - Verify regex works before adding to config
5. Follow debug workflow if 0% - plan.md Step 4 has solutions
6. Track time - Compare to 30 min target

---

Previous Attempts (For Context)

Attempt 1 (2026-02-10 AM):

• Result: 0% detection
• Reason: Skipped Phase 4 entirely (didn't create extractors)
• Time: 20 minutes (incomplete)

Attempt 2 (2026-02-10 PM):

• Result: 0% detection
• Reason: Created 7 extractors but with wrong subject format (missing msgqueue/ prefix)
• Time: 70 minutes (trial-and-error)

This Attempt (2026-02-11):

• Expected: 100% detection
• Expected time: ≤30 minutes
• Using: New documentation fixes

---

Ready to Start!

Next command:

cargo check  # Pre-flight: verify code compiles

Then follow plan.md Day 3 workflow step-by-step.

Good luck! The docs should guide you to 100% detection without trial-and-error.