# Daily Run Automations

Scripts that run periodically to keep the development loop operational.

## Scripts

| Script | Source | Purpose | Trigger |
|--------|--------|---------|---------|
| `cycle_retro.py` | `../../scripts/cycle_retro.py` | Log structured retrospective data | Post-cycle |
| `loop_guard.py` | `../../scripts/loop_guard.py` | Idle detection with exponential backoff | Pre-cycle |
| `triage_score.py` | `../../scripts/triage_score.py` | Mechanical issue scoring | Every 10 cycles |
| `orchestrator.py` | `orchestrator.py` | The 10-minute ritual — Daily Run agenda + review | Manual |

## Running

These scripts are invoked by the dev loop orchestrator (Hermes). Manual execution:

```bash
# After a successful cycle
python3 scripts/cycle_retro.py --cycle 42 --success --issue 123 --type bug

# Check if queue has work (exits 0 if ready, 1 if idle)
python3 scripts/loop_guard.py

# Score open issues
python3 scripts/triage_score.py

# Generate Daily Run agenda (10-minute ritual)
python3 timmy_automations/daily_run/orchestrator.py

# Generate agenda with day summary (review mode)
python3 timmy_automations/daily_run/orchestrator.py --review

# Output as JSON
python3 timmy_automations/daily_run/orchestrator.py --review --json
```

## Daily Run Orchestrator

The orchestrator script connects to local Gitea and:

1. **Fetches candidate issues** matching configured labels (default: `daily-run` + `size:XS`/`size:S`)
2. **Generates a concise agenda** with up to 3 items for approximately 10 minutes of work
3. **Review mode** (`--review`): Summarizes the last 24 hours — issues/PRs touched, items closed/merged, test failures

### Configuration

Edit `timmy_automations/config/daily_run.json` under the `orchestrator` section:

```json
{
  "orchestrator": {
    "candidate_labels": ["daily-run"],
    "size_labels": ["size:XS", "size:S"],
    "max_agenda_items": 3,
    "lookback_hours": 24,
    "agenda_time_minutes": 10
  }
}
```

| Option | Description | Default |
|--------|-------------|---------|
| `candidate_labels` | Labels to identify Daily Run candidates | `["daily-run"]` |
| `size_labels` | Size labels to filter by | `["size:XS", "size:S"]` |
| `max_agenda_items` | Maximum items in agenda | `3` |
| `lookback_hours` | Hours to look back in review mode | `24` |
| `agenda_time_minutes` | Target time budget for agenda | `10` |

### Environment Variables

Override config via environment:

```bash
export TIMMY_GITEA_API="http://localhost:3000/api/v1"
export TIMMY_REPO_SLUG="rockachopa/Timmy-time-dashboard"
export TIMMY_GITEA_TOKEN="your-token-here"  # Alternative to token file
```

### Output Format

**Standard mode:**
```
============================================================
📋 DAILY RUN AGENDA
============================================================
Generated: 2026-03-21T15:16:02+00:00
Time budget: 10 minutes
Candidates considered: 5

1. #123 [XS] [infra]
   Title: Fix config loading bug
   Action: FIX
   URL: http://localhost:3000/rockachopa/Timmy-time-dashboard/issues/123
...
```

**Review mode (`--review`):**
Adds a day summary section showing issues touched, closed, PRs merged, and any test failures.

## Configuration

See `../config/automations.json` for automation manifests and `../config/daily_run.json` for scheduling and orchestrator settings.