Phase 5: Species Hunt Engine and Features

Created: .planning/phases/05-collection-journal-export/05-CONTEXT.md

Decisions Captured

Daily Species Hunt (HUNT-01, HUNT-02)

• D-01: Deterministic tiered multi-target challenge based on local date (YYYY-MM-DD) hash with individual progress pips.
• D-02: Automatic day-wide matching across all walk sessions (00:00 to 23:59 local time).
• D-03: Celebratory modal dialog with stamp animation, audio chime (if sound enabled), haptic feedback, and dated field badge.
• D-04: Featured as a hero card on /collection and an expandable top HUD pill during walks on /walk.

Life List Display & Taxon Grouping (LIFE-01)

• D-05: Horizontal category filter pills with live counters (All, Trees, Flowers, Plants, Birds, Insects, Fungus, Other).
• D-06: Canonical species cards with Seen Nx encounter counts, avoiding duplicate card clutter.
• D-07: Real-time text search (common/scientific name) and sort dropdown (Most Recent, Most Seen, Alphabetical A–Z).
• D-08: Evocative field notebook empty state with warm serif prose and a direct Start a Walk button.

Journal Timeline & Activity Heatmap (JOUR-01, JOUR-02)

• D-09: Rolling multi-week activity matrix (12 weeks, 7 days high) with 4 terracotta intensity levels based on mileage and find count.
• D-10: Chronological date-grouped walk timeline with summary cards (distance, duration, specimen badges, audio note count).
• D-11: Split inspection layout for /journal/[walkId] with MapLibre header map (route polyline + specimen/audio pins) and tabbed details.
• D-12: Editable walk title and safe delete confirmation prompt offering to preserve confirmed finds in Life List or purge entirely.

Obsidian ZIP Export & Settings Data Management (EXPT-01, SETT-01)

• D-13: Structured Naturalist Vault ZIP archive with /Walks, /Species, /Media, and treads-backup.json at root.
• D-14: Rich Obsidian-native YAML properties with Dataview and Map plugin compatibility.
• D-15: Full 1024px JPEGs and recorded WebM audio clips in /Media with sanitized slug filenames referenced via ![[...]].
• D-16: Dedicated /settings route with storage persistence status, audio/haptic preferences, instant export download, and a two-step Danger Zone modal for IndexedDB reset.

---

▶ Next Up — [Treads] Field Walking & Specimen Journal

Phase 5: Collection, Journal & Export — Build the life list collection screen, daily species hunt gamification, past walk timeline with activity heatmap, and full Obsidian-compatible ZIP export.

Run:

⚠ UI-SPEC.md missing for Phase 5

▶ Recommended next step: /gsd-ui-phase 5 — generate UI design contract before planning

───────────────────────────────────────────────

Also available:

• /gsd-plan-phase 5 --skip-ui — plan without UI-SPEC (not recommended for frontend phases)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► UI-SPEC READY ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 5: Collection, Journal & Export — UI design contract approved

Dimensions: 6/6 passed (Copywriting, Visuals, Color, Typography, Spacing, Registry Safety) UI Considerations: 29 state conditions resolved & covered

Contract Location: .planning/phases/05-collection-journal-export/05-UI-SPEC.md

───────────────────────────────────────────────────────────────

▶ Next Up — [Treads] Field Walking & Specimen Journal

Plan Phase 5 — planner will use 05-CONTEXT.md and 05-UI-SPEC.md as design context

Run:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PLANS CREATED FOR PHASE 5 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 5: Collection, Journal & Export (2 plans generated, verified, and committed)

Artifacts Created:

• Technical Research: .planning/phases/05-collection-journal-export/05-RESEARCH.md
• Validation Strategy: .planning/phases/05-collection-journal-export/05-VALIDATION.md
• Plan 05-01: .planning/phases/05-collection-journal-export/05-01-PLAN.md
• Plan 05-02: .planning/phases/05-collection-journal-export/05-02-PLAN.md

---

Plan Breakdown

1. Plan 05-01: Daily Species Hunt Engine, Celebration Dialog & Life List Collection (HUNT-01, HUNT-02, LIFE-01)

   • Task 1: Deterministic FNV-1a date-hash rule engine (lib/hunt.ts) generating multi-target objectives with automatic day-wide matching from db.entries.
   • Task 2: Daily Hunt UI components (components/hunt/daily-hunt-card.tsx), expandable walk HUD pill (components/hunt/daily-hunt-hud-pill.tsx), and stamp celebration modal dialog (daily-hunt-celebration-dialog.tsx) with haptic pulse.
   • Task 3: Life List collection page (app/collection/page.tsx) with horizontal category filter pills, real-time search & sort, canonical de-duplicated species cards (Seen Nx count), and field notebook empty states.

2. Plan 05-02: Activity Heatmap, Walk Detail Replay, Obsidian ZIP Exporter & Settings Data Management (JOUR-01, JOUR-02, EXPT-01, SETT-01)

   • Task 1: Client-side JSZip Obsidian Naturalist Vault exporter (lib/export.ts) writing /Walks/*.md, /Species/*.md, /Media/*, and treads-backup.json with Dataview-compatible YAML frontmatter and wiki-links.
   • Task 2: Chronological walk history timeline (app/journal/page.tsx) with rolling 12-week activity heatmap (activity-heatmap.tsx) and rich walk summary cards.
   • Task 3: Walk detail inspection view (app/journal/[walkId]/page.tsx) featuring MapLibre trail route replay, specimen/audio pins, telemetry tabs, editable walk title, and safe deletion.
   • Task 4: Settings page (app/settings/page.tsx) with storage persistence indicator, audio/haptic preferences, export download button, and two-step Danger Zone type-to-confirm modal for IndexedDB reset.

---

▶ Next Up — [Treads] Field Walking & Specimen Journal

Execute the plans for Phase 5:

Phase 5 (Collection, Journal & Export) has been executed and verified on branch phase-5-collection-journal-export.

---

Key Deliverables & Systems Built

1. Life List & Daily Species Hunt (HUNT-01, HUNT-02, LIFE-01)

• Deterministic Daily Challenge Engine (lib/hunt.ts): 32-bit FNV-1a date hashing (YYYY-MM-DD) cycling across 14 challenge templates, matching confirmed organisms against today's target criteria.
• Hero & HUD Integration:
  • components/hunt/daily-hunt-card.tsx: Hero banner with target cards, glowing progress pips, and difficulty badges.
  • components/hunt/daily-hunt-hud-pill.tsx: Compact live HUD pill with popover for live walks.
  • components/hunt/daily-hunt-celebration-dialog.tsx: Celebratory stamp ring animation with motion/react and physical haptic pulse.
• De-duplicated Life List (app/collection/page.tsx):
  • Taxonomic category filtering pills (Plants, Birds, Fungi, Insects, Trees, Flowers).
  • Search by common or binomial scientific names.
  • Canonical SpeciesCard with "Seen Nx" count badge and latest photo thumbnail.

2. Field Journal Timeline & 12-Week Activity Heatmap (JOUR-01)

• Rolling Activity Matrix (components/journal/activity-heatmap.tsx): 12-week grid (84 daily cells) with 4 terracotta intensity levels based on mileage and confirmed finds, streak tracking, and horizontal touch scrolling.
• Timeline & Walk Cards (app/journal/page.tsx & components/journal/walk-card.tsx): Date-grouped past walks ("Today", "Yesterday", "October 8, 2026") displaying duration, distance, specimen photo thumbnail reels, and voice note counts.
• Warm Empty State: Serif-styled callout "No expeditions recorded yet" with primary "Start Walk" CTA.

3. Walk Detail Inspection & Safe Deletion (JOUR-02)

• Route Replay Page (app/journal/[walkId]/page.tsx):
  • Interactive MapLibre GL header map rendering complete glowing terracotta polyline trail, taxon-coded specimen pins, and audio note pins with coordinate auto-bounds fitting.
  • Tabbed inspector for Stats & Telemetry (distance, duration, min/km pace, GPS points), Confirmed Specimens (cards linking to /entry/[id]), and Voice Notes (interactive audio player with transcript).
  • Click-to-edit inline walk title persisting directly to walk.title in IndexedDB.
  • Safe deletion dialog offering a choice between "Preserve Confirmed Species" (keeps finds in Life List) and "Purge Walk and Entries".

4. Obsidian Naturalist Vault ZIP Exporter (EXPT-01)

• JSZip Packaging Engine (lib/export.ts):
  • Dataview-compatible YAML frontmatter generator for walks (type: walk, date, duration_minutes, distance_meters, species: ["[[Species/...]]"]) and species (type: species, scientific_name, kind, first_seen, wikipedia).
  • Strict filename sanitization stripping illegal filesystem characters.
  • Generates /Walks/, /Species/, /Media/ (1024px JPEGs + recorded WebM audio), and treads-backup.json.
  • Client-side download trigger with real-time compression progress indicator.

5. Settings & Two-Step Danger Zone (SETT-01)

• Data Sovereignty Center (app/settings/page.tsx):
  • Live storage persistence checker (navigator.storage.persisted(), navigator.storage.persist()) with "Persisted" / "Best Effort" badge.
  • Storage quota & usage estimate display.
  • Sound effects (Cuelume) and haptic vibration preference toggles saved to db.settings.
  • Color mode switcher (ThemeToggle).
  • Two-step type-to-confirm modal requiring typing "DELETE" before wiping IndexedDB tables.

---

Verification

• scripts/test-hunt-engine.ts: PASS (hash repeatability, criteria filtering, daily challenge evaluation).
• scripts/test-export-engine.ts: PASS (ZIP structure, YAML frontmatter, media files, backup JSON).
• npx tsc --noEmit: 0 errors.
• npm run build: PASS (18/18 routes statically or dynamically compiled in 4.9s).
• All changes staged and committed under commit 02e87a7 on branch phase-5-collection-journal-export.

Phase 5 Verification Complete: Collection, Journal & Export

All requirements, decisions, and deliverables for Phase 5 have been verified and documented. All files have been staged and committed on branch phase-5-collection-journal-export.

---

Verification Summary

Metric	Status / Count
Phase Status	PASSED (100% complete)
Requirements Verified	7 / 7 (HUNT-01, HUNT-02, LIFE-01, JOUR-01, JOUR-02, EXPT-01, SETT-01)
Decisions Satisfied	16 / 16 (D-01 through D-16)
UAT Checkpoints	17 / 17 Passed (0 issues, 0 blocked, 0 skipped)
Automated Test Suites	scripts/test-hunt-engine.ts (PASS), scripts/test-export-engine.ts (PASS)
Static Type Check	npx tsc --noEmit (0 errors)
Production Build	npm run build (18/18 routes compiled successfully in 4.9s)

---

Key Verification Documents Created

1. 05-UAT.md:

   • 17 test checkpoints tracking daily hunt deterministic generation, HUD integration, celebration dialog, Life List de-duplication, category filtering, 12-week heatmap, MapLibre route replay, safe deletion, Obsidian ZIP generation, Dataview frontmatter, and two-step Danger Zone modal.
   • Status: complete.

2. 05-VERIFICATION.md:

   • Full requirement cross-reference and traceability matrix.
   • Complete decision matrix mapping each architecture decision to implementation files.
   • Test suite execution output and production build logs.
   • Security and data sovereignty validation audit.

3. ROADMAP.md & STATE.md:

   • Phase 5 marked complete (all 2 plans executed).
   • Project progress updated to 5/6 phases complete (83%).

---

Commit Details

• Commit: f5402af (docs(phase-5): add 05-UAT and 05-VERIFICATION, mark phase complete)
• Branch: phase-5-collection-journal-export
• Working Tree: Clean (0 uncommitted files)