jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e758f2ebfb
stemedb/applications/aphoria/dogfood/CLEANUP-PLAN.md
jml e758f2ebfb feat(aphoria): implement programmatic extractors for Option<T> semantics 
Completes Task #3 of httpclient dogfooding with 100% detection rate (7/7 violations).

## New Extractors

- **OptionBoundsExtractor**: Detects Option<T> fields set to None (unbounded)
- **OptionValueExtractor**: Extracts values from Some(n) for threshold checks

Both extractors use context-aware pattern matching to understand Rust Option<T>
semantics, which declarative extractors cannot handle.

## Implementation

**Files Created**:
- applications/aphoria/src/extractors/option_bounds.rs (257 lines)
- applications/aphoria/src/extractors/option_value.rs (277 lines)
- applications/aphoria/docs/examples/extractors/programmatic-option-semantics.md

**Files Modified**:
- applications/aphoria/src/extractors/mod.rs - Added module declarations
- applications/aphoria/src/extractors/registry.rs - Registered extractors
- applications/aphoria/dogfood/httpclient/.aphoria/claims.toml - Added 4 claims
- applications/aphoria/dogfood/httpclient/TASK-1-SUMMARY.md - Task #3 completion

## Results

| Metric | Value |
|--------|-------|
| Detection Rate | 100% (7/7 violations) |
| Improvement | +29 percentage points (from 71%) |
| New Violations | 2 (max_redirects, max_retries unbounded) |
| Unit Tests | 13 (all passing) |

## Two-Claim Strategy

For each bounded Option<T> field:
1. **configured** claim - Detects None (unbounded)
2. **max_value** claim - Validates Some(n) threshold

Example:
- `max_redirects: None` → CONFLICT (not configured)
- `max_redirects: Some(20)` → CONFLICT (exceeds 10)
- `max_redirects: Some(5)` → PASS

## Enterprise Quality

✓ Proper error handling (no unwrap/expect)
✓ Comprehensive tests (6+7 unit tests)
✓ Full documentation with examples
✓ Reusable for 10+ similar patterns
✓ Screening patterns for performance

## Cachewrap Dogfood

Also includes complete cachewrap dogfood exercise:
- 10 claims for Redis cache wrapper
- Day 1-5 summaries
- Full retrospective and evaluation
- Declarative extractors for all patterns

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-11 06:43:10 +00:00

11 KiB
Raw Blame History

Dogfood Directory Cleanup Plan

Date: 2026-02-11 Status: Ready to execute

Issues Found

1. ❌ Database Files Committed to Git (CRITICAL)

Problem: .aphoria/db/ directories are committed and should be ignored.

Evidence:

$ git ls-files | grep "\.aphoria/db"
applications/aphoria/dogfood/dbpool/.aphoria/db/store/fjall/journals/0
applications/aphoria/dogfood/dbpool/.aphoria/db/store/fjall/partitions/default/config
applications/aphoria/dogfood/dbpool/.aphoria/db/store/fjall/partitions/default/levels
applications/aphoria/dogfood/dbpool/.aphoria/db/store/fjall/partitions/default/manifest
applications/aphoria/dogfood/dbpool/.aphoria/db/store/fjall/version
applications/aphoria/dogfood/dbpool/.aphoria/db/store/redb/data.redb
applications/aphoria/dogfood/dbpool/.aphoria/db/wal/0000000000000000.wal

Size: These are persistent Aphoria databases (not code).

Impact:

  • Bloats repository size
  • Contains runtime state (not source code)
  • Should be generated locally, not committed

Fix:

  1. Add **/.aphoria/db/ to .gitignore
  2. Remove from git: git rm -r --cached applications/aphoria/dogfood/*/.aphoria/db/
  3. Commit removal

2. ⚠️ Temporary/Dated Documentation Files

Files to evaluate:

A. PROJECT2-QUICKSTART-DEPRECATED.md (12K)

  • Status: Explicitly marked DEPRECATED
  • Action: DELETE (superseded by individual project READMEs)

B. PROJECT2-READY.md (12K)

  • Status: Dated documentation (2026-02-10)
  • Content: "All documentation complete, ready for Project 2 launch"
  • Action: ARCHIVE to archive/ or DELETE (info is in README.md)

C. SYSTEMATIC-FIXES-2026-02-10.md (12K)

  • Status: Dated fix documentation
  • Content: Documents invalid comparison mode fixes
  • Action: ARCHIVE to archive/fixes/ (historical record)

D. SYSTEMATIC-FIXES-COMPLETE.md (8K)

  • Status: Follow-up to above
  • Content: "Fixes complete" summary
  • Action: ARCHIVE to archive/fixes/ (historical record)

E. verify-project2-ready.sh (4K)

  • Status: Shell script for verification
  • Content: Checks if Project 2 prerequisites are met
  • Action: KEEP if useful, or ARCHIVE to archive/scripts/

3. ✅ Large But Correct (No Action Needed)

target/ directories (550M, 784M, 979M):

  • ✅ Already in .gitignore (**/target/)
  • ✅ NOT tracked by git
  • ✅ Build artifacts (correct to ignore)

Action: None - working as intended.

Recommended Actions

Priority 1: Fix .gitignore and Remove DB Files (5 minutes)

Why: Bloats repo, wrong content type for git

Steps:

# 1. Add to .gitignore
echo "**/.aphoria/db/" >> .gitignore

# 2. Remove from git (keeps local files)
git rm -r --cached applications/aphoria/dogfood/dbpool/.aphoria/db/

# 3. Verify removal
git status | grep ".aphoria/db"
# Should show: deleted from git, not in working tree changes

# 4. Commit
git commit -m "chore(dogfood): remove .aphoria/db/ from git tracking

Database files should be generated locally, not committed.
Added **/.aphoria/db/ to .gitignore.
"

Priority 2: Archive Dated Documentation (5 minutes)

Why: Reduces clutter, preserves history

Steps:

cd applications/aphoria/dogfood

# Create archive structure
mkdir -p archive/fixes archive/deprecated

# Move dated fix documentation
mv SYSTEMATIC-FIXES-2026-02-10.md archive/fixes/
mv SYSTEMATIC-FIXES-COMPLETE.md archive/fixes/

# Move deprecated files
mv PROJECT2-QUICKSTART-DEPRECATED.md archive/deprecated/
mv PROJECT2-READY.md archive/deprecated/

# Move script (optional - if not actively used)
mv verify-project2-ready.sh archive/deprecated/

# Create archive README
cat > archive/README.md << 'EOF'
# Dogfood Archive

This directory contains historical documentation and scripts.

## Contents

### `fixes/` - Historical Fix Documentation
- `SYSTEMATIC-FIXES-2026-02-10.md` - Invalid comparison mode fixes across projects
- `SYSTEMATIC-FIXES-COMPLETE.md` - Fix completion summary

### `deprecated/` - Superseded Documentation
- `PROJECT2-QUICKSTART-DEPRECATED.md` - Old quickstart (superseded by individual READMEs)
- `PROJECT2-READY.md` - Project 2 launch readiness doc (info now in main README)
- `verify-project2-ready.sh` - Prerequisite verification script

These files are kept for historical reference but are no longer active documentation.
EOF

# Commit
git add archive/
git rm PROJECT2-QUICKSTART-DEPRECATED.md PROJECT2-READY.md \
        SYSTEMATIC-FIXES-2026-02-10.md SYSTEMATIC-FIXES-COMPLETE.md \
        verify-project2-ready.sh
git commit -m "chore(dogfood): archive dated documentation

Moved to archive/:
- Dated fix docs (SYSTEMATIC-FIXES-*)
- Deprecated quickstart guides
- Project 2 readiness docs (info now in main README)

These are preserved for historical reference but no longer active.
"

Priority 3: Clean Local Build Artifacts (Optional, 1 minute)

Why: Frees disk space (2.3GB total)

Steps:

cd applications/aphoria/dogfood

# Clean Rust build artifacts (NOT tracked by git)
rm -rf httpclient/target/
rm -rf msgqueue/target/
rm -rf dbpool/target/
rm -rf cachewrap/target/ # If exists

# Clean Aphoria databases (NOT tracked by git after fix)
rm -rf httpclient/.aphoria/db/
rm -rf msgqueue/.aphoria/db/
rm -rf dbpool/.aphoria/db/
rm -rf cachewrap/.aphoria/db/ # If exists

echo "Freed ~2.3GB of disk space"

Note: These will be regenerated when you run cargo build or aphoria scan --mode persistent.

After Cleanup: Expected State

Directory Structure

dogfood/
├── README.md                     # Main dogfood guide (KEEP)
├── archive/                      # Historical docs (NEW)
│   ├── README.md
│   ├── fixes/
│   │   ├── SYSTEMATIC-FIXES-2026-02-10.md
│   │   └── SYSTEMATIC-FIXES-COMPLETE.md
│   └── deprecated/
│       ├── PROJECT2-QUICKSTART-DEPRECATED.md
│       ├── PROJECT2-READY.md
│       └── verify-project2-ready.sh
├── cachewrap/                    # Cache client exercise (KEEP)
│   ├── README.md
│   ├── plan.md
│   ├── SETUP-EVALUATION.md
│   ├── .aphoria/
│   │   ├── config.toml
│   │   ├── claims.toml
│   │   └── db/                   # ← NOT in git (ignored)
│   ├── docs/
│   └── src/
├── dbpool/                       # Database pool exercise (KEEP)
│   ├── README.md
│   ├── plan.md
│   ├── .aphoria/
│   │   ├── config.toml
│   │   ├── claims.toml
│   │   └── db/                   # ← NOT in git (ignored)
│   ├── docs/
│   ├── eval/
│   ├── eval-archive-2026-02-09/
│   ├── src/
│   └── target/                   # ← NOT in git (ignored)
├── httpclient/                   # HTTP client exercise (KEEP)
│   ├── README.md
│   ├── plan.md
│   ├── DAY5-DOGFOODING-REPORT.md
│   ├── .aphoria/
│   │   ├── config.toml
│   │   ├── claims.toml
│   │   └── db/                   # ← NOT in git (ignored)
│   ├── docs/
│   ├── src/
│   └── target/                   # ← NOT in git (ignored)
└── msgqueue/                     # Message queue exercise (KEEP)
    ├── README.md
    ├── plan.md
    ├── .aphoria/
    │   ├── config.toml
    │   ├── claims.toml
    │   └── db/                   # ← NOT in git (ignored)
    ├── docs/
    ├── eval/
    ├── src/
    └── target/                   # ← NOT in git (ignored)

.gitignore Changes

# Before
**/target/

# After
**/target/
**/.aphoria/db/
**/.aphoria/wal/

Git Status (After)

$ git status
modified:   .gitignore
deleted:    applications/aphoria/dogfood/PROJECT2-QUICKSTART-DEPRECATED.md
deleted:    applications/aphoria/dogfood/PROJECT2-READY.md
deleted:    applications/aphoria/dogfood/SYSTEMATIC-FIXES-2026-02-10.md
deleted:    applications/aphoria/dogfood/SYSTEMATIC-FIXES-COMPLETE.md
deleted:    applications/aphoria/dogfood/verify-project2-ready.sh
deleted:    applications/aphoria/dogfood/dbpool/.aphoria/db/...
new file:   applications/aphoria/dogfood/archive/README.md
new file:   applications/aphoria/dogfood/archive/fixes/...
new file:   applications/aphoria/dogfood/archive/deprecated/...

Rationale

Why Archive (Not Delete)?

Keep historical context:

  • SYSTEMATIC-FIXES-* documents a real bug (invalid comparison modes)
  • Shows evolution of project (mistakes → fixes)
  • Useful for future contributors ("why did we change this?")

But remove from main directory:

  • Dated (2026-02-10)
  • Superseded by corrected docs in individual projects
  • Clutter for new users

Archive = best of both worlds

Why Remove .aphoria/db/ from Git?

It's runtime state, not source:

  • Generated by aphoria scan --mode persistent
  • Contains Episteme database files (fjall, redb, WAL)
  • User-specific (not shareable)

Analogy:

  • Like committing node_modules/ or target/
  • Build artifacts, not code

Correct workflow:

  • User clones repo
  • User runs aphoria scan → generates .aphoria/db/
  • .aphoria/db/ stays local (gitignored)

Validation

After cleanup, verify:

# 1. Database files no longer tracked
git ls-files | grep "\.aphoria/db"
# Expected: No output

# 2. Database files still exist locally (if you want them)
ls applications/aphoria/dogfood/dbpool/.aphoria/db/
# Expected: Directories still there (not deleted, just untracked)

# 3. Archive created
ls applications/aphoria/dogfood/archive/
# Expected: README.md, fixes/, deprecated/

# 4. Dated files gone from main directory
ls applications/aphoria/dogfood/*.md
# Expected: Only README.md

# 5. .gitignore updated
grep "\.aphoria/db" .gitignore
# Expected: **/.aphoria/db/

Estimated Time

  • Priority 1 (gitignore + remove DB): 5 minutes
  • Priority 2 (archive docs): 5 minutes
  • Priority 3 (clean local builds): 1 minute (optional)

Total: ~10 minutes

Alternative: Minimal Cleanup (Just Fix Git)

If you want minimal changes:

# 1. Add to .gitignore
echo "**/.aphoria/db/" >> .gitignore

# 2. Remove from git
git rm -r --cached applications/aphoria/dogfood/*/,aphoria/db/

# 3. Commit
git commit -m "chore: ignore .aphoria/db/ directories"

Time: 2 minutes

This fixes the critical issue (database files in git) without touching documentation.

Recommendation

Execute Priority 1 + Priority 2 (10 minutes total)

Why:

  • Priority 1: Critical (fixes repo bloat)
  • Priority 2: Good housekeeping (dated docs confuse new users)
  • Priority 3: Optional (just frees local disk space)

After cleanup:

  • ✅ No database files in git
  • ✅ Clean documentation structure
  • ✅ Historical docs preserved in archive/
  • ✅ Main directory has only active docs

Ready to execute? Let me know and I'll run the cleanup commands.