# Build Contract: agentkit-cli v0.44.0 — `agentkit timeline`

**Version:** 0.44.0  
**Feature:** `agentkit timeline` — visual quality timeline from history DB  
**Baseline tests:** 1794 (verify with `python3 -m pytest -q --tb=no` before starting)  
**Target:** ≥1794 + 40 new = ≥1834 passing, zero failures  
**Repo:** ~/repos/agentkit-cli/  
**PyPI package:** agentkit-cli  

---

## Objective

Build `agentkit timeline` — generates a dark-theme HTML chart showing composite score progression over time for a given project (or all projects). Reads from the existing SQLite history DB. Shareable via `--share`. Complements `agentkit certify`: "here's the journey, here's the cert."

---

## Deliverables

### D1: TimelineEngine — `agentkit_cli/timeline.py` (≥12 tests)

TimelineEngine class with:
- `load_runs(project: str | None, limit: int = 100)` — query history DB, return sorted runs
- `build_chart_data(runs)` — extract dates + composite scores + per-tool scores (lint, code quality, context, test coverage)
- `compute_stats(runs)` — min/max/avg/trend direction (improving/stable/declining), streak (N consecutive above threshold)
- Returns structured dict ready for HTML template injection

If no project name given, loads all projects with grouping by project name.

### D2: `agentkit timeline` CLI command — `agentkit_cli/commands/timeline_cmd.py` (≥10 tests)

```
agentkit timeline [--project NAME] [--limit N] [--since YYYY-MM-DD] [--output FILE] [--share] [--json]
```

Flags:
- `--project` — filter to one project (default: all)
- `--limit N` — max runs to show (default: 50)
- `--since DATE` — only runs after this date (YYYY-MM-DD)
- `--output FILE` — write HTML to file (default: timeline.html)
- `--share` — publish to here.now and print URL (uses existing publish_to_herenow helper)
- `--json` — output raw chart data as JSON (stdout)

Rich console output: print summary table (project, run count, latest score, trend direction) before writing HTML.

### D3: Dark-theme HTML timeline report (≥10 tests)

Standalone HTML file, no external dependencies (embed Chart.js from CDN with integrity hash, or use pure SVG/canvas if CDN is unavailable).

Layout:
- Header: "Agent Quality Timeline" + project name + date range
- Main chart: line chart, x-axis = date, y-axis = composite score (0-100), one line per project if multi-project
- Per-tool breakdown: smaller sparklines below (lint score, code quality, context freshness, test count) — use simple CSS-bar sparklines, no extra JS
- Stats panel: min/max/avg, trend arrow (↑↓→), streak badge ("12 runs above 80")
- Footer: "Generated by agentkit-cli v0.44.0"

Test the HTML structure (section headers present, data injected, no broken template syntax) without browser rendering.

### D4: `agentkit run --timeline` integration (≥8 tests)

Add `--timeline` flag to `agentkit run`:
- After run completes, generate timeline HTML and open it (or just write it)
- Combine with `--share` to auto-publish

Wire `agentkit timeline` into `agentkit doctor` output as a "run `agentkit timeline` to see history" hint when history DB has ≥3 entries.

### D5: Docs, CHANGELOG, version bump, BUILD-REPORT (≥5 tests)

- README: add "Timeline" section under Commands, with example output description
- CHANGELOG: add v0.44.0 entry
- pyproject.toml: bump version from 0.43.0 → 0.44.0
- `agentkit_cli/__init__.py`: bump `__version__` from "0.43.0" → "0.44.0"
- BUILD-REPORT.md: created with deliverables checklist, test count, test command output

---

## Implementation Notes

- History DB path: use `HistoryDB` from `agentkit_cli/history.py` — do NOT re-implement DB access
- Here.now publish: use `publish_to_herenow(html_content, filename)` from `agentkit_cli/publish.py` if it exists, else replicate the pattern from `analyze_cmd.py` or `certify_cmd.py`
- Chart.js CDN: `https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js` — embed as `<script src=...>` in HTML
- If history DB is empty (no runs), print a friendly message and exit 0: "No history found. Run `agentkit run` first."
- Multi-project mode: group by project_name column; if missing, group by target path

---

## Stop Conditions

STOP and report back (do NOT continue) if:
- Any existing test fails after your changes (baseline 1794 must stay green)
- `agentkit timeline` crashes with an unhandled exception on a non-empty history DB
- HTML output is empty or missing the chart data

DO NOT:
- Push to GitHub (build-loop handles that)
- Publish to PyPI (build-loop handles that)
- Create new GitHub repos
- Modify any file outside ~/repos/agentkit-cli/

---

## Definition of Done

1. `python3 -m pytest -q --tb=no` shows ≥1834 passed, 0 failed
2. `agentkit timeline --help` works
3. `agentkit timeline --json` outputs valid JSON with chart data fields
4. BUILD-REPORT.md exists with all deliverables checked
5. pyproject.toml and `__init__.py` both show version "0.44.0"
