# Autodo Changelog & Reporting

**Date**: 2026-03-01
**Status**: Design

## Problem

Autodo runs work autonomously — scans, fixes, code changes — but produces no persistent record of what it did, what it found, or what it changed. Without this, there's no way to review its work, catch regressions, or build trust in its autonomy.

## Design: Running Changelog

Autodo maintains a structured changelog at `helm/autodo/changelog/`. Each entry is a timestamped record with metadata.

### Entry Types (colored pills in UI)

| Pill | Color | Type | Description |
|------|-------|------|-------------|
| `SCAN` | cyan | Read-only | Looked for issues/TODOs, found N items |
| `FEAT` | green | Feature | Added capability, new template, new scanner |
| `FIX` | red | Bug/regression | Fixed a detected issue |
| `REFACTOR` | purple | Code quality | Cleanup, antipattern removal, style |
| `TRIAGE` | yellow | Classification | Evaluated severity, filed/deprioritized items |

### Entry Schema

```yaml
id: "2026-03-01T10:41:00-auto-001"
type: scan | feat | fix | refactor | triage
source_template: tpl-error-swallowing-sweep    # what triggered this
timestamp: 2026-03-01T10:41:00-08:00

# What happened
summary: "Scanned 8 directories for silent error swallowing"
findings: 35                                    # for scans
items_filed: 8                                  # autodo items created

# For code changes (fix, feat, refactor)
changes:
  - file: helm/recap.py
    line: 226
    what: "Replaced return False with raise in generate_recap exception handler"
    tested: true
    test_command: "python -m pytest helm/tests/ -k recap"
    test_result: "4 passed"

# Provenance
session_id: "abc123..."                         # which session did the work
commit: "deadbeef"                              # if committed
```

### Rules for Code Changes

1. **Location required** — every `changes` entry states file + line + what
2. **Test evidence required** — `tested: true` with command + result, or `tested: false` with reason
3. **No silent changes** — if autodo touches code, it appears in the changelog. Period.

### Storage

```
helm/autodo/changelog/
├── 2026-03/                     # monthly directories
│   ├── 2026-03-01.yaml          # daily files
│   ├── 2026-03-02.yaml
│   └── ...
└── index.yaml                   # running summary stats
```

Daily files are append-only YAML lists. `index.yaml` tracks aggregate counts by type and month.

### UI (watch dashboard)

Changelog view in watch:
- Reverse-chronological feed
- Colored pills for entry type
- Expandable details for code changes (diff preview)
- Filter by type, date range, template
- "N changes today" badge on dashboard header

### Integration Points

| System | Role |
|--------|------|
| **doctor** | Runs scans → files SCAN entries |
| **autodo** | Executes fixes → files FIX/FEAT/REFACTOR entries |
| **watch** | Displays changelog feed |
| **helm API** | Serves changelog data to watch |

### Principles

- **Append-only** — never edit or delete changelog entries
- **Machine-readable** — YAML, not markdown, so watch can render it
- **Test evidence before merge** — code changes without test evidence get flagged
- **Human-reviewable** — daily files are small enough to skim