# Structured Activity Logging — HoffDesk Spec v1.0 **Status:** Draft **Adopted:** 2026-04-23 --- ## Purpose Replace freeform daily notes with structured, queryable activity logs. Preserve the file-based, sovereign architecture. Add run grouping and metrics. --- ## File Structure ``` memory/ ├── 2026-04-22.md # Legacy format (preserved) ├── 2026-04-23.md # New structured format ├── runs/ │ └── 20260423_wv_001.md # Run detail files (optional) └── LOGGING.md # This spec ``` --- ## Entry Format Each activity is a markdown list item with JSON frontmatter: ```markdown - Started drafting spec at Matt's request ``` ### Required Fields | Field | Type | Description | |-------|------|-------------| | `type` | enum | `task.started`, `task.progress`, `task.completed`, `task.failed` | | `run_id` | string | Grouping identifier for related actions | | `title` | string | Brief headline, ≤80 chars | | `agent` | string | Agent handle: `wadsworth`, `socrates`, `daedalus` | | `time` | ISO8601 | UTC timestamp | ### Optional Fields | Field | Type | Description | |-------|------|-------------| | `state` | enum | `thinking`, `working`, `idle`, `done`, `error` | | `detail` | string | What specifically happened | | `tokens` | number | Approximate tokens used | | `duration_ms` | number | Time elapsed | | `tool` | string | Tool name invoked | | `tool_input` | string | Brief summary, ≤200 chars | | `tool_output` | string | Brief result, ≤200 chars | | `progress` | number | 0-100 for multi-step tasks | --- ## Run ID Format ``` YYYYMMDD_AGENT_SEQ ``` | Segment | Meaning | Example | |---------|---------|---------| | `YYYYMMDD` | Date | `20260423` | | `AGENT` | 2-letter code | `wv` = wadsworth, `sc` = socrates, `dd` = daedalus | | `SEQ` | Sequence number | `001`, `002`... | ### Examples - `20260423_wv_001` — Wadsworth's first run today - `20260423_sc_003` — Socrates' third run today - `20260423_dd_001` — Daedalus' first run today --- ## Usage Patterns ### Starting a Run ```markdown - Starting integration test for v2 pipeline ``` ### Progress Update ```markdown - Uvicorn now accessible via Tailscale ``` ### Completion ```markdown - ✅ Pipeline test successful ``` ### Failure (with recovery) ```markdown - ❌ Content rejected, escalating to Matt ``` --- ## Querying Logs ### Find All Runs Today ```bash grep -o '"run_id": "[^"]*"' memory/2026-04-23.md | sort | uniq ``` ### Find Specific Run ```bash grep "20260423_wv_001" memory/2026-04-23.md ``` ### Find Failed Tasks ```bash grep '"type": "task.failed"' memory/2026-04-23.md ``` ### Find Tool Usage ```bash grep '"tool": "memory_search"' memory/2026-04-23.md ``` ### Duration Analysis ```bash grep -o '"duration_ms": [0-9]*' memory/2026-04-23.md | awk '{sum+=$2; count++} END {print "Avg:", sum/count/1000, "s"}' ``` --- ## Migration Path ### Phase 1: Dual Format (Now) - New entries use structured format - Legacy entries preserved as-is - Both coexist in same file ### Phase 2: Backfill (Optional) - Convert high-value legacy entries - Leave routine entries as-is ### Phase 3: Tooling (Later) - `log_activity()` helper function - Query CLI for memory files - Dashboard view (optional) --- ## Example Full Day ```markdown # 2026-04-23 — Session Log ## Morning - Starting Phase 1.5/2 integration - All 8 API endpoints responding - Templates now served by API - Port 8000 now accessible - ✅ Both agents Phase 1.5/2 complete ## Evening - Matt reports generated content is "fever dream hallucination" - Root cause: model + prompt mismatch - Options A (fix), B (upgrade), C (hybrid) presented to Matt ``` --- ## Validation Before appending, validate: 1. JSON is valid 2. Required fields present 3. `run_id` format correct 4. `time` is valid ISO8601 5. `type` is in allowed enum Invalid entries fall back to legacy format (no JSON comment). --- **Version:** 1.0 **Last Updated:** 2026-04-23 **Next Review:** After 7 days of usage