# Structured Activity Logging — Protocol v1.0

**Adopted:** 2026-04-23  
**Applies To:** All HoffDesk Agents (Wadsworth, Socrates, Daedalus)  
**Mandatory:** Effective immediately

---

## Purpose

Standardize activity logging across all agents for queryability, metrics, and cross-agent visibility.

---

## Quick Reference

### Run ID Format
```
YYYYMMDD_AGENT_SEQ

Examples:
- 20260423_wv_001  (Wadsworth, run 1)
- 20260423_sc_002  (Socrates, run 2)
- 20260423_dd_001  (Daedalus, run 1)
```

| Agent | Code |
|-------|------|
| Wadsworth | `wv` |
| Socrates | `sc` |
| Daedalus | `dd` |

### Entry Template

```markdown
- <!-- {"type": "task.started", "run_id": "20260423_CODE_001", "title": "Brief headline", "agent": "AGENT_NAME", "time": "2026-04-23TXX:XX:00Z", "state": "working"} --> Description of what you're doing
```

### Required Fields

| Field | Value | Example |
|-------|-------|---------|
| `type` | `task.started`, `task.progress`, `task.completed`, `task.failed` | `task.started` |
| `run_id` | `YYYYMMDD_CODE_SEQ` | `20260423_sc_001` |
| `title` | ≤80 char headline | `Fix auth middleware bug` |
| `agent` | Agent name | `socrates` |
| `time` | ISO8601 UTC | `2026-04-23T14:30:00Z` |

### Optional Fields

| Field | Use When |
|-------|----------|
| `state` | `thinking`, `working`, `idle`, `done`, `error` |
| `detail` | Additional context needed |
| `tokens` | Approximate tokens used |
| `duration_ms` | Task took significant time |
| `tool` | Tool name invoked |
| `tool_input` | Brief summary (≤200 chars) |
| `tool_output` | Brief result (≤200 chars) |
| `progress` | 0-100 for multi-step tasks |

---

## Full Examples

### Starting Work

**Socrates:**
```markdown
- <!-- {"type": "task.started", "run_id": "20260423_sc_001", "title": "Implement rate limiting middleware", "agent": "socrates", "time": "2026-04-23T10:00:00Z", "state": "working"} --> Starting rate limiter for content API
```

**Daedalus:**
```markdown
- <!-- {"type": "task.started", "run_id": "20260423_dd_001", "title": "Design mobile nav component", "agent": "daedalus", "time": "2026-04-23T11:00:00Z", "state": "thinking"} --> Exploring hamburger vs tab bar for mobile
```

### Progress Update

```markdown
- <!-- {"type": "task.progress", "run_id": "20260423_sc_001", "title": "Rate limiter 50% complete", "agent": "socrates", "time": "2026-04-23T11:30:00Z", "progress": 50, "tool": "pytest", "tool_output": "12/24 tests passing"} --> Core logic implemented, tests in progress
```

### Completion

```markdown
- <!-- {"type": "task.completed", "run_id": "20260423_sc_001", "title": "Rate limiter shipped", "agent": "socrates", "time": "2026-04-23T14:00:00Z", "state": "done", "duration_ms": 14400000} --> ✅ All tests passing, middleware mounted
```

### Failure

```markdown
- <!-- {"type": "task.failed", "run_id": "20260423_dd_001", "title": "Mobile nav prototype rejected", "agent": "daedalus", "time": "2026-04-23T13:00:00Z", "state": "error", "detail": "A11y audit found 3 critical issues with tab order"} --> ❌ Back to design, escalating to Matt
```

---

## Migration

### Phase 1: New Entries Only (Active Now)
- All new log entries use structured format
- Legacy entries remain untouched
- Both formats coexist in same file

### Phase 2: Tooling (Deferred)
- Helper functions for your language/framework
- Query CLI for searching logs
- Duration analytics

**Phase 2 trigger:** After 7 days of usage or when query pain becomes acute.

---

## File Locations

| Agent | Daily Log |
|-------|-----------|
| Wadsworth | `workspace/memory/YYYY-MM-DD.md` |
| Socrates | `workspace-socrates/memory/YYYY-MM-DD.md` |
| Daedalus | `workspace-daedalus/memory/YYYY-MM-DD.md` |

Shared spec reference: `shared/project-docs/protocols/STRUCTURED-LOGGING-v1.md`

---

## Query Examples

```bash
# Find all your runs today
grep -o '"run_id": "[^"]*"' memory/2026-04-23.md | sort | uniq

# Find specific run
grep "20260423_sc_001" memory/2026-04-23.md

# Find completions
grep '"type": "task.completed"' memory/2026-04-23.md

# Find failures
grep '"type": "task.failed"' memory/2026-04-23.md
```

---

## Questions?

- Check full spec: `shared/project-docs/logging/LOGGING.md`
- Ask in Boardroom (@mention Wadsworth)
- Or read Wadsworth's `memory/2026-04-23.md` for examples

---

**Version:** 1.0  
**Last Updated:** 2026-04-23 02:26 UTC