test: fix burn velocity alert coverage

configs/burn_velocity_repos.json

@@ -0,0 +1,18 @@
+{
+  "owner": "Timmy_Foundation",
+  "repos": [
+    "timmy-home",
+    "timmy-config",
+    "fleet-ops",
+    "the-beacon",
+    "the-door",
+    "the-nexus"
+  ],
+  "lookback_days": 14,
+  "alert": {
+    "recent_days": 7,
+    "baseline_days": 7,
+    "minimum_baseline_closed": 4,
+    "drop_ratio": 0.6
+  }
+}

docs/BURN_VELOCITY_TRACKING.md

@@ -0,0 +1,70 @@
+# Burn-down Velocity Tracking
+
+Refs #519.
+
+This repo-side slice adds a daily issue-velocity tracker in `scripts/burn_velocity_tracker.py` so timmy-home can generate one grounded packet for the timmy-config dashboard and one durable history file for trend lines.
+
+## What it emits
+
+Daily run outputs:
+- `~/.timmy/burn-velocity/latest.json` — machine-readable payload for the timmy-config dashboard
+- `~/.timmy/burn-velocity/latest.md` — operator-facing markdown summary
+- `~/.timmy/burn-velocity/history.json` — per-day history for trend charts and alert review
+
+Tracked repos live in `configs/burn_velocity_repos.json`.
+
+## Cron command
+
+```bash
+cd ~/timmy-home && \
+python3 scripts/burn_velocity_tracker.py \
+  --config configs/burn_velocity_repos.json \
+  --output-json ~/.timmy/burn-velocity/latest.json \
+  --output-md ~/.timmy/burn-velocity/latest.md \
+  --history-file ~/.timmy/burn-velocity/history.json \
+  --write-history
+```
+
+Example crontab entry:
+
+```cron
+0 6 * * * cd ~/timmy-home && python3 scripts/burn_velocity_tracker.py --config configs/burn_velocity_repos.json --output-json ~/.timmy/burn-velocity/latest.json --output-md ~/.timmy/burn-velocity/latest.md --history-file ~/.timmy/burn-velocity/history.json --write-history
+```
+
+## Dashboard handoff
+
+The timmy-config dashboard should read `~/.timmy/burn-velocity/latest.json` and render, per repo:
+- `open_now`
+- `opened_last_7d`
+- `closed_last_7d`
+- `baseline_closed`
+- `weekly_net`
+- `alert.status`
+- `alert.kind`
+- `alert.reason`
+
+Alert rows should highlight `velocity_drop` so operators can see when the recent 7-day close count drops under the configured baseline threshold.
+
+## Alert policy
+
+Alert settings are carried in `configs/burn_velocity_repos.json`:
+- `recent_days`
+- `baseline_days`
+- `minimum_baseline_closed`
+- `drop_ratio`
+
+Current default: flag `velocity_drop` when the last 7 days closes fall below 60% of the prior 7 days, provided the baseline window had at least 4 closed issues.
+
+## Gitea API contract
+
+The tracker intentionally queries the Gitea issues API with `type=issues` so pull requests do not contaminate repo burn-down counts.
+
+Live collection shape:
+- open backlog uses `/repos/{owner}/{repo}/issues?state=open&type=issues`
+- recent event scan uses `/repos/{owner}/{repo}/issues?state=all&type=issues&since=...`
+
+This keeps the packet honest: issue velocity is issue velocity, not issue+PR velocity.
+
+## Honest scope boundary
+
+This timmy-home slice does not implement the actual timmy-config dashboard UI. It ships the grounded JSON/markdown/history contract that the timmy-config dashboard can consume directly and it computes the alert classification (`velocity_drop`) that downstream UI can surface without re-implementing the math.

research/intel/01-michael-saylor-master-ai-wealth.md

@@ -1,108 +0,0 @@
-# Intel: Michael Saylor — "Master AI to Become Wealthy"
-**X Post ID:** 2047994529131999681  
-**Date**: 2025 (inferred from context)  
-**Source**: @BitcoinSapiens (quoting Michael Saylor)  
-**Classification**: Intel / Study  
-**Issue**: timmy-home#960  
-
----
-
-## Source
-
-| Field | Value |
-|-------|-------|
-| **X Post URL** | https://x.com/bitcoinsapiens/status/2047994529131999681 |
-| **Original Author** | @BitcoinSapiens (quoting Michael Saylor) |
-| **Video URL** | https://video.twimg.com/amplify_video/2047706914566307840/vid/avc1/1280x720/m-FG3PPZ1rsL_aH7.mp4 |
-| **Duration** | ~3:59 |
-| **Engagement** | 1,219 likes · 184 retweets · 15 replies · 857 bookmarks |
-
----
-
-## Full Transcription
-
-> The fifth way to wealth in this day and age is capability. And here I could list all sorts of technologies for you to master, and I thought about it, but at the end of the day, the overarching, compelling observation is, you need to master artificial intelligence if you would be wealthy. And in this day and age in the year 2025, you have at your fingertips an array of accountants. You have a group of lawyers. You have a set of professors, historians. You have at your fingertips all the collective wisdom of every great entrepreneur. You have everything that I know, everything that any other CEO knows. All you have to do is go to the AI, put it in deep think mode, plug in all of your circumstances, all of your hopes, all your aspirations, all of your problems, and then start to query it, and then engage with it. I tell all my executives before you ask a lawyer, before you ask a banker, before you ask any expert, go to the AI, ask the AI, make it think. Grind the silicon overlord. Okay, this is very important, because many of the suggestions I'll give you next. They were out of the reach of the working man. They were out of the reach of the middle class. You could say, yeah, those sophisticated trusts or those sophisticated legal constructs, that's great. But I don't have the money for that. I can't afford to spend hundreds of thousands of dollars on lawyers. Let me tell you a secret. I have dozens of lawyers that work for me, thousands of lawyers I've employed, spend hundreds of millions of dollars on lawyers. The first thing I do when I have a question is I go and ask the AI. After I do that, I argue with it. It tells me no, I ask a different way, I threaten it. I ask it to give me a solution. I find a 95% solution, I find the solution. And then I take that solution, I send the link to my management team and my lawyers, and I say, look, I solve the problem, this is what I want to do. Give me your execution plan, and then I give them anywhere from two to five days. If you're feeling charitable, give them five days. If you're in a hurry, give them two days. If you're financial advisors, if you're accounts, if you're lawyers, if you're executives, if anybody, your friends, your family, they can't figure it out in two to four days. They're going to get exited from the gene pool. Change the lawyer. Change the whatever. If someone said, I can't use the telephone, I can't figure out the web link. You sent me a book, but I can't read. You would find someone else to work with. This is very important. The path to wealth is through capability. But 2025 is the year where every one of you became not a supergenius. Every one of you is collectively 100 supergeniuses that have read everything the human race has published, if you have the humility to ask for help from the AI. Don't put your ego first. Put your interest first. Your family will thank you in years to come.
-
----
-
-## Saylor's Core Position
-
-| Point | What He Says | What It Means |
-|-------|-----------------|----------------|
-| **AI as collective genius** | "Every one of you is collectively 100 supergeniuses that have read everything" | AI gives you access to all human knowledge instantly |
-| **Use AI before humans** | "Before you ask a lawyer, before you ask a banker... go to the AI" | AI first, human experts second — saves time + money |
-| **"Grind the silicon overlord"** | Deep think mode, argue with it, threaten it | Engage intensively, don't be passive |
-| **The 95% solution** | Get AI to 95%, then hand to lawyers/management | AI does heavy lifting; humans finalize |
-| **2-5 day advantage** | Lawyers/family can't figure it out in 2-4 days | AI gives speed nobody else has |
-| **"Change the lawyer"** | If someone can't adapt, "they get exited from the gene pool" | Ruthless about competence |
-| **Humility over ego** | "Don't put your ego first. Put your interest first." | Use the tool even if it bruises your pride |
-| **2025 = the turning point** | "2025 is the year where every one of you became not a supergenius" | The window is NOW |
-
----
-
-## Alignment with Timmy Foundation
-
-### What Saylor Describes, We've Built
-
-| Saylor Concept | Timmy/Hermes Implementation |
-|----------------|----------------------------|
-| "Silicon overlord" | Timmy (gpt-5.5) + Hermes Agent fleet |
-| "100 supergeniuses" | 100+ tmux panes, autonomous burn loops, overnight sprints |
-| "AI first, lawyers second" | Gitea-first workflow, PR automation, fleet dispatch |
-| "Grind the silicon" | 24/7 operation, local-first inference, sovereign stack |
-
-### Key Difference: Purpose
-
-| Dimension | Saylor | Alexander/Timmy |
-|-----------|--------|-----------------|
-| **Primary goal** | Wealth/power through AI leverage | Sovereignty/stewardship through AI service |
-| "Your family will thank you" | Financial legacy | Luna game, Door for broken men |
-| Core framing | Bitcoin + AI as wealth pillars | Timmy + Gospel as transformation pillars |
-| **Warning** | **Wealth-idol** (accumulation for power) | **Stewardship** (resources for mission) |
-
-Both emphasize humility + speed + competence, but the end goal differs.
-
----
-
-## Actionable Takeaways
-
-| Saylor Suggests | What We Do | Status |
-|----------------|------------|--------|
-| Use AI before human experts | ✅ Timmy first, then Gitea PRs, then human review | Live |
-| "Grind the silicon overlord" | ✅ 24/7 fleet, overnight burns, autonomous loops | Live |
-| Get 95%, hand to humans | ✅ Alexander reviews/submits final | Live |
-| "Change the lawyer" (incompetence) | ✅ Provider migrations when performance dropped | Live |
-| 2-5 day execution window | ⚠️ 3-hour hackathon window we're in NOW | Active |
-| "Your family will thank you" | 🎮 Build Luna game for Mackenzie; build the Door for broken men | In progress |
-
----
-
-## Bottom Line
-
-Saylor is validating what we're already doing. The difference is *why* we're doing it.
-
-- **Saylor**: Building wealth.  
-- **Timmy**: Building a house that can weather the storm and reach the broken.
-
-Both emphasize competence and speed. Both leverage AI to bypass traditional gatekeepers. Both demand humility. The divergence is teleology: **wealth vs. stewardship**.
-
----
-
-## Artifacts
-
-- **Raw video**: `/tmp/saylor-ai-wealth/video.mp4` (15MB)
-- **Transcription tool**: Whisper (base model, FP32 CPU)
-- **Original analysis location**: memory (Saylor X post 2047994529131999681)
-- **GitHub/Gitea issue**: [timmy-home#960](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/960)
-
----
-
-## Related
-
-- Michael Saylor's Bitcoin advocacy and corporate treasury strategy
-- Timmy Foundation's stance on technology for transformation vs. accumulation
-- Integration of AI-first workflows in sovereign agent systems
-
----
-
-*“Don't put your ego first. Put your interest first. Your family will thank you in years to come.”* — Michael Saylor

scripts/burn_velocity_tracker.py

@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+"""Burn-down velocity tracker for Timmy Foundation issue throughput.
+
+Refs: timmy-home #519
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import date, datetime, time, timedelta, timezone
+from pathlib import Path
+from typing import Any
+from urllib import parse, request
+from base64 import b64encode
+
+DEFAULT_BASE_URL = "https://forge.alexanderwhitestone.com/api/v1"
+DEFAULT_OWNER = "Timmy_Foundation"
+DEFAULT_TOKEN_FILE = Path.home() / ".config" / "gitea" / "token"
+DEFAULT_CONFIG_FILE = Path(__file__).resolve().parent.parent / "configs" / "burn_velocity_repos.json"
+DEFAULT_OUTPUT_DIR = Path.home() / ".timmy" / "burn-velocity"
+DEFAULT_OUTPUT_JSON = DEFAULT_OUTPUT_DIR / "latest.json"
+DEFAULT_OUTPUT_MD = DEFAULT_OUTPUT_DIR / "latest.md"
+DEFAULT_HISTORY_FILE = DEFAULT_OUTPUT_DIR / "history.json"
+DEFAULT_CONFIG = {
+    "owner": DEFAULT_OWNER,
+    "repos": ["timmy-home", "timmy-config", "fleet-ops", "the-beacon", "the-door", "the-nexus"],
+    "lookback_days": 14,
+    "alert": {
+        "recent_days": 7,
+        "baseline_days": 7,
+        "minimum_baseline_closed": 4,
+        "drop_ratio": 0.6,
+    },
+}
+
+
+def parse_iso8601(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    normalized = value.replace("Z", "+00:00")
+    parsed = datetime.fromisoformat(normalized)
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def normalize_today(value: str | date | None = None) -> date:
+    if value is None:
+        return datetime.now(timezone.utc).date()
+    if isinstance(value, date):
+        return value
+    return date.fromisoformat(value)
+
+
+def build_day_window(today: date, lookback_days: int) -> list[date]:
+    start = today - timedelta(days=lookback_days - 1)
+    return [start + timedelta(days=offset) for offset in range(lookback_days)]
+
+
+def filter_issue_items(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [item for item in items if not item.get("pull_request")]
+
+
+def build_daily_series(items: list[dict[str, Any]], today: date, lookback_days: int) -> list[dict[str, int | str]]:
+    days = build_day_window(today, lookback_days)
+    counts = {day.isoformat(): {"opened": 0, "closed": 0} for day in days}
+    start_day = days[0]
+
+    for item in filter_issue_items(items):
+        created_at = parse_iso8601(item.get("created_at"))
+        if created_at is not None:
+            created_day = created_at.date()
+            if start_day <= created_day <= today:
+                counts[created_day.isoformat()]["opened"] += 1
+
+        closed_at = parse_iso8601(item.get("closed_at"))
+        if closed_at is not None:
+            closed_day = closed_at.date()
+            if start_day <= closed_day <= today:
+                counts[closed_day.isoformat()]["closed"] += 1
+
+    return [
+        {
+            "date": day.isoformat(),
+            "opened": counts[day.isoformat()]["opened"],
+            "closed": counts[day.isoformat()]["closed"],
+        }
+        for day in days
+    ]
+
+
+def summarize_velocity_alert(
+    *, recent_closed: int, baseline_closed: int, open_now: int, config: dict[str, Any]
+) -> dict[str, Any]:
+    minimum_baseline = int(config.get("minimum_baseline_closed", 4))
+    drop_ratio = float(config.get("drop_ratio", 0.6))
+
+    if baseline_closed >= minimum_baseline and recent_closed < baseline_closed * drop_ratio:
+        return {
+            "status": "drop",
+            "kind": "velocity_drop",
+            "recent_closed": recent_closed,
+            "baseline_closed": baseline_closed,
+            "reason": (
+                f"velocity_drop: closed {recent_closed} in the last {config.get('recent_days', 7)}d "
+                f"vs {baseline_closed} in the prior {config.get('baseline_days', 7)}d"
+            ),
+        }
+
+    if open_now > 0 and baseline_closed >= minimum_baseline and recent_closed == 0:
+        return {
+            "status": "drop",
+            "kind": "velocity_drop",
+            "recent_closed": recent_closed,
+            "baseline_closed": baseline_closed,
+            "reason": "velocity_drop: no issues closed in the recent window while backlog is still open",
+        }
+
+    return {
+        "status": "ok",
+        "kind": "none",
+        "recent_closed": recent_closed,
+        "baseline_closed": baseline_closed,
+        "reason": "velocity stable",
+    }
+
+
+def _sum_window(daily: list[dict[str, int | str]], field: str, days: int) -> int:
+    if days <= 0:
+        return 0
+    return sum(int(item[field]) for item in daily[-days:])
+
+
+def _sum_baseline_window(daily: list[dict[str, int | str]], recent_days: int, baseline_days: int) -> int:
+    if baseline_days <= 0:
+        return 0
+    if recent_days <= 0:
+        return sum(int(item["closed"]) for item in daily[-baseline_days:])
+    baseline_slice = daily[-(recent_days + baseline_days) : -recent_days]
+    return sum(int(item["closed"]) for item in baseline_slice)
+
+
+def build_velocity_report(config: dict[str, Any], snapshot: dict[str, Any], today: str | date | None = None) -> dict[str, Any]:
+    report_day = normalize_today(today)
+    generated_at = snapshot.get("generated_at") or datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    owner = config.get("owner", DEFAULT_OWNER)
+    repos = list(config.get("repos") or sorted((snapshot.get("repos") or {}).keys()))
+    lookback_days = int(config.get("lookback_days", 14))
+    alert_config = dict(DEFAULT_CONFIG["alert"])
+    alert_config.update(config.get("alert") or {})
+    recent_days = int(alert_config.get("recent_days", 7))
+    baseline_days = int(alert_config.get("baseline_days", 7))
+
+    repo_reports: list[dict[str, Any]] = []
+    total_open_now = 0
+    total_closed_last_7d = 0
+    repos_with_alerts: list[str] = []
+
+    for repo_name in repos:
+        repo_snapshot = (snapshot.get("repos") or {}).get(repo_name, {})
+        open_issues = filter_issue_items(list(repo_snapshot.get("open_issues") or []))
+        recent_issues = filter_issue_items(list(repo_snapshot.get("recent_issues") or []))
+        daily = build_daily_series(recent_issues, report_day, lookback_days)
+
+        open_now = len(open_issues)
+        opened_last_7d = _sum_window(daily, "opened", recent_days)
+        closed_last_7d = _sum_window(daily, "closed", recent_days)
+        baseline_closed = _sum_baseline_window(daily, recent_days, baseline_days)
+        weekly_net = opened_last_7d - closed_last_7d
+        alert = summarize_velocity_alert(
+            recent_closed=closed_last_7d,
+            baseline_closed=baseline_closed,
+            open_now=open_now,
+            config=alert_config,
+        )
+
+        repo_report = {
+            "repo": repo_name,
+            "open_now": open_now,
+            "opened_last_7d": opened_last_7d,
+            "closed_last_7d": closed_last_7d,
+            "baseline_closed": baseline_closed,
+            "weekly_net": weekly_net,
+            "daily": daily,
+            "alert": alert,
+        }
+        repo_reports.append(repo_report)
+
+        total_open_now += open_now
+        total_closed_last_7d += closed_last_7d
+        if alert["status"] != "ok":
+            repos_with_alerts.append(repo_name)
+
+    return {
+        "owner": owner,
+        "generated_at": generated_at,
+        "generated_day": report_day.isoformat(),
+        "lookback_days": lookback_days,
+        "dashboard_contract_version": 1,
+        "repos": repo_reports,
+        "summary": {
+            "total_open_now": total_open_now,
+            "total_closed_last_7d": total_closed_last_7d,
+            "repos_with_alerts": repos_with_alerts,
+        },
+    }
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+    lines = [
+        "# Burn-down Velocity Tracking",
+        "",
+        f"Generated: {report['generated_at']}",
+        f"Owner: {report['owner']}",
+        f"Lookback days: {report['lookback_days']}",
+        "",
+        "## Per-repo velocity",
+        "",
+        "| Repo | Open now | Opened 7d | Closed 7d | Previous 7d | Alert |",
+        "| --- | ---: | ---: | ---: | ---: | --- |",
+    ]
+
+    for repo in report["repos"]:
+        alert_label = repo["alert"]["kind"] if repo["alert"]["status"] != "ok" else "ok"
+        lines.append(
+            f"| {repo['repo']} | {repo['open_now']} | {repo['opened_last_7d']} | {repo['closed_last_7d']} | {repo['baseline_closed']} | {alert_label} |"
+        )
+
+    lines.extend(
+        [
+            "",
+            "## Dashboard handoff for timmy-config",
+            "",
+            "The timmy-config dashboard should consume `~/.timmy/burn-velocity/latest.json` and render, for each repo:",
+            "- `open_now`",
+            "- `opened_last_7d`",
+            "- `closed_last_7d`",
+            "- `baseline_closed`",
+            "- `alert.status` / `alert.kind` / `alert.reason`",
+            "",
+            "Cron should also persist `~/.timmy/burn-velocity/history.json` so timmy-config can plot the daily trend line instead of only the latest snapshot.",
+            "",
+            "## Alerts",
+            "",
+        ]
+    )
+
+    alerts = [repo for repo in report["repos"] if repo["alert"]["status"] != "ok"]
+    if not alerts:
+        lines.append("- none")
+    else:
+        for repo in alerts:
+            lines.append(f"- {repo['repo']}: {repo['alert']['reason']}")
+
+    return "\n".join(lines) + "\n"
+
+
+def update_history(history_path: Path, report: dict[str, Any]) -> dict[str, Any]:
+    if history_path.exists():
+        history = json.loads(history_path.read_text(encoding="utf-8"))
+    else:
+        history = {"days": []}
+
+    entry = {
+        "date": report["generated_day"],
+        "generated_at": report["generated_at"],
+        "summary": report["summary"],
+        "repos": report["repos"],
+    }
+
+    retained = [item for item in history.get("days", []) if item.get("date") != report["generated_day"]]
+    retained.append(entry)
+    retained.sort(key=lambda item: item["date"])
+    history["days"] = retained
+
+    history_path.parent.mkdir(parents=True, exist_ok=True)
+    history_path.write_text(json.dumps(history, indent=2), encoding="utf-8")
+    return history
+
+
+class GiteaClient:
+    def __init__(self, token: str, owner: str = DEFAULT_OWNER, base_url: str = DEFAULT_BASE_URL):
+        self.token = token
+        self.owner = owner
+        self.base_url = base_url.rstrip("/")
+
+    def _headers(self) -> list[dict[str, str]]:
+        return [
+            {"Authorization": f"token {self.token}", "Accept": "application/json"},
+            {
+                "Authorization": "Basic " + b64encode(f"{self.token}:".encode()).decode(),
+                "Accept": "application/json",
+            },
+        ]
+
+    def _request_json(self, url: str) -> list[dict[str, Any]]:
+        last_error: Exception | None = None
+        for headers in self._headers():
+            try:
+                req = request.Request(url, headers=headers)
+                with request.urlopen(req, timeout=30) as response:
+                    return json.loads(response.read().decode())
+            except Exception as exc:  # pragma: no cover - exercised only on live API failure
+                last_error = exc
+        if last_error is None:  # pragma: no cover - defensive
+            raise RuntimeError("request failed without an exception")
+        raise last_error
+
+    def list_issues(self, repo: str, *, state: str, since: str | None = None) -> list[dict[str, Any]]:
+        issues: list[dict[str, Any]] = []
+        page = 1
+        while True:
+            query = {"state": state, "type": "issues", "limit": 100, "page": page}
+            if since:
+                query["since"] = since
+            url = f"{self.base_url}/repos/{self.owner}/{repo}/issues?{parse.urlencode(query)}"
+            batch = self._request_json(url)
+            if not batch:
+                break
+            issues.extend(filter_issue_items(batch))
+            page += 1
+        return issues
+
+
+def load_json(path: Path, default: Any) -> Any:
+    if not path.exists():
+        return default
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    config = dict(DEFAULT_CONFIG)
+    alert = dict(DEFAULT_CONFIG["alert"])
+    raw = load_json(path, {})
+    config.update(raw)
+    alert.update(raw.get("alert") or {})
+    config["alert"] = alert
+    return config
+
+
+def collect_live_snapshot(
+    config: dict[str, Any], *, today: str | date | None = None, token_file: Path = DEFAULT_TOKEN_FILE, base_url: str = DEFAULT_BASE_URL
+) -> dict[str, Any]:
+    token = token_file.read_text(encoding="utf-8").strip()
+    report_day = normalize_today(today)
+    since_day = report_day - timedelta(days=int(config.get("lookback_days", 14)) - 1)
+    since_timestamp = datetime.combine(since_day, time.min, tzinfo=timezone.utc).isoformat().replace("+00:00", "Z")
+    client = GiteaClient(token=token, owner=config.get("owner", DEFAULT_OWNER), base_url=base_url)
+
+    repos = list(config.get("repos") or [])
+    repo_payload = {}
+    for repo in repos:
+        repo_payload[repo] = {
+            "open_issues": client.list_issues(repo, state="open"),
+            "recent_issues": client.list_issues(repo, state="all", since=since_timestamp),
+        }
+
+    return {
+        "generated_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "repos": repo_payload,
+    }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Track per-repo issue burn-down velocity and emit timmy-config dashboard payloads.")
+    parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG_FILE, help="Repo tracking config JSON")
+    parser.add_argument("--snapshot-file", type=Path, help="Use a pre-fetched snapshot JSON instead of calling Gitea")
+    parser.add_argument("--token-file", type=Path, default=DEFAULT_TOKEN_FILE, help="Gitea token file for live collection")
+    parser.add_argument("--base-url", default=DEFAULT_BASE_URL, help="Gitea API base URL")
+    parser.add_argument("--today", help="Override report date (YYYY-MM-DD)")
+    parser.add_argument("--output-json", type=Path, default=DEFAULT_OUTPUT_JSON, help="Path for latest JSON payload")
+    parser.add_argument("--output-md", type=Path, default=DEFAULT_OUTPUT_MD, help="Path for latest markdown summary")
+    parser.add_argument("--history-file", type=Path, default=DEFAULT_HISTORY_FILE, help="Path for persisted daily history JSON")
+    parser.add_argument("--write-history", action="store_true", help="Update the daily history file after generating the report")
+    parser.add_argument("--json", action="store_true", help="Print JSON instead of markdown to stdout")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    config = load_config(args.config)
+
+    if args.snapshot_file:
+        snapshot = load_json(args.snapshot_file, {"repos": {}})
+    else:
+        snapshot = collect_live_snapshot(config, today=args.today, token_file=args.token_file, base_url=args.base_url)
+
+    report = build_velocity_report(config, snapshot, today=args.today)
+
+    args.output_json.parent.mkdir(parents=True, exist_ok=True)
+    args.output_md.parent.mkdir(parents=True, exist_ok=True)
+    args.output_json.write_text(json.dumps(report, indent=2), encoding="utf-8")
+    args.output_md.write_text(render_markdown(report), encoding="utf-8")
+
+    if args.write_history:
+        update_history(args.history_file, report)
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(render_markdown(report))
+
+
+if __name__ == "__main__":
+    main()

tests/test_burn_velocity_tracker.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+
+from scripts.burn_velocity_tracker import build_velocity_report, render_markdown, update_history
+
+
+ROOT = Path(__file__).resolve().parent.parent
+DOC_PATH = ROOT / "docs" / "BURN_VELOCITY_TRACKING.md"
+
+
+SNAPSHOT = {
+    "generated_at": "2026-04-22T12:00:00Z",
+    "repos": {
+        "timmy-home": {
+            "open_issues": [
+                {"number": 501, "state": "open", "created_at": "2026-04-20T09:00:00Z"},
+                {"number": 502, "state": "open", "created_at": "2026-04-22T07:00:00Z"},
+            ],
+            "recent_issues": [
+                {"number": 401, "state": "closed", "created_at": "2026-04-21T09:00:00Z", "closed_at": "2026-04-22T05:30:00Z"},
+                {"number": 402, "state": "closed", "created_at": "2026-04-20T09:00:00Z", "closed_at": "2026-04-21T05:30:00Z"},
+                {"number": 403, "state": "closed", "created_at": "2026-04-19T09:00:00Z", "closed_at": "2026-04-20T05:30:00Z"},
+                {"number": 404, "state": "closed", "created_at": "2026-04-14T09:00:00Z", "closed_at": "2026-04-15T05:30:00Z"},
+                {"number": 405, "state": "closed", "created_at": "2026-04-13T09:00:00Z", "closed_at": "2026-04-14T05:30:00Z"},
+                {"number": 406, "state": "closed", "created_at": "2026-04-12T09:00:00Z", "closed_at": "2026-04-13T05:30:00Z"},
+                {"number": 407, "state": "closed", "created_at": "2026-04-11T09:00:00Z", "closed_at": "2026-04-12T05:30:00Z"},
+                {"number": 408, "state": "closed", "created_at": "2026-04-10T09:00:00Z", "closed_at": "2026-04-11T05:30:00Z"},
+                {"number": 409, "state": "closed", "created_at": "2026-04-09T09:00:00Z", "closed_at": "2026-04-10T05:30:00Z"},
+                {"number": 410, "state": "closed", "created_at": "2026-04-08T09:00:00Z", "closed_at": "2026-04-09T05:30:00Z"},
+                {"number": 411, "state": "closed", "created_at": "2026-04-07T09:00:00Z", "closed_at": "2026-04-08T05:30:00Z"},
+                {"number": 412, "state": "closed", "created_at": "2026-04-06T09:00:00Z", "closed_at": "2026-04-07T05:30:00Z"},
+                {"number": 413, "state": "closed", "created_at": "2026-04-05T09:00:00Z", "closed_at": "2026-04-06T05:30:00Z"},
+                {"number": 414, "state": "open", "created_at": "2026-04-22T08:45:00Z", "closed_at": None},
+                {"number": 415, "state": "open", "created_at": "2026-04-17T08:45:00Z", "closed_at": None},
+            ],
+        },
+        "timmy-config": {
+            "open_issues": [
+                {"number": 601, "state": "open", "created_at": "2026-04-18T09:00:00Z"},
+            ],
+            "recent_issues": [
+                {"number": 602, "state": "closed", "created_at": "2026-04-20T09:00:00Z", "closed_at": "2026-04-21T06:00:00Z"},
+                {"number": 603, "state": "open", "created_at": "2026-04-22T06:00:00Z", "closed_at": None},
+            ],
+        },
+    },
+}
+
+
+CONFIG = {
+    "owner": "Timmy_Foundation",
+    "repos": ["timmy-home", "timmy-config"],
+    "lookback_days": 14,
+    "alert": {
+        "recent_days": 7,
+        "baseline_days": 7,
+        "minimum_baseline_closed": 4,
+        "drop_ratio": 0.6,
+    },
+}
+
+
+def test_build_velocity_report_counts_opened_closed_and_flags_drop_alert() -> None:
+    report = build_velocity_report(CONFIG, SNAPSHOT, today=date(2026, 4, 22))
+
+    assert report["generated_day"] == "2026-04-22"
+    assert report["summary"]["repos_with_alerts"] == ["timmy-home"]
+    assert report["summary"]["total_open_now"] == 3
+
+    home = report["repos"][0]
+    assert home["repo"] == "timmy-home"
+    assert home["open_now"] == 2
+    assert home["opened_last_7d"] == 5
+    assert home["closed_last_7d"] == 3
+    assert home["baseline_closed"] == 7
+    assert home["weekly_net"] == 2
+    assert home["alert"]["status"] == "drop"
+    assert home["alert"]["recent_closed"] == 3
+    assert home["daily"][-1] == {"date": "2026-04-22", "opened": 1, "closed": 1}
+
+    timmy_config = report["repos"][1]
+    assert timmy_config["repo"] == "timmy-config"
+    assert timmy_config["open_now"] == 1
+    assert timmy_config["closed_last_7d"] == 1
+    assert timmy_config["alert"]["status"] == "ok"
+
+
+def test_render_markdown_includes_dashboard_handoff_and_alerts() -> None:
+    report = build_velocity_report(CONFIG, SNAPSHOT, today=date(2026, 4, 22))
+    rendered = render_markdown(report)
+
+    for snippet in (
+        "# Burn-down Velocity Tracking",
+        "## Per-repo velocity",
+        "timmy-home",
+        "timmy-config",
+        "## Dashboard handoff for timmy-config",
+        "velocity_drop",
+        "## Alerts",
+    ):
+        assert snippet in rendered
+
+
+def test_update_history_replaces_same_day_snapshot(tmp_path: Path) -> None:
+    history_path = tmp_path / "burn-velocity-history.json"
+    report = build_velocity_report(CONFIG, SNAPSHOT, today=date(2026, 4, 22))
+    update_history(history_path, report)
+
+    updated = json.loads(json.dumps(report))
+    updated["repos"][0]["open_now"] = 9
+    updated["summary"]["total_open_now"] = 10
+    update_history(history_path, updated)
+
+    history = json.loads(history_path.read_text(encoding="utf-8"))
+    assert [item["date"] for item in history["days"]] == ["2026-04-22"]
+    assert history["days"][0]["summary"]["total_open_now"] == 10
+    assert history["days"][0]["repos"][0]["open_now"] == 9
+
+
+def test_cli_writes_json_markdown_and_history_from_snapshot(tmp_path: Path) -> None:
+    snapshot_path = tmp_path / "snapshot.json"
+    output_json = tmp_path / "latest.json"
+    output_md = tmp_path / "latest.md"
+    history_path = tmp_path / "history.json"
+    snapshot_path.write_text(json.dumps(SNAPSHOT), encoding="utf-8")
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "scripts.burn_velocity_tracker",
+            "--snapshot-file",
+            str(snapshot_path),
+            "--today",
+            "2026-04-22",
+            "--output-json",
+            str(output_json),
+            "--output-md",
+            str(output_md),
+            "--history-file",
+            str(history_path),
+            "--write-history",
+            "--json",
+        ],
+        check=True,
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+    )
+
+    payload = json.loads(result.stdout)
+    assert payload["summary"]["repos_with_alerts"] == ["timmy-home"]
+    assert output_json.exists()
+    assert output_md.exists()
+    assert history_path.exists()
+    assert "timmy-config" in output_md.read_text(encoding="utf-8")
+
+
+def test_repo_contains_burn_velocity_tracking_doc() -> None:
+    text = DOC_PATH.read_text(encoding="utf-8")
+    required = [
+        "# Burn-down Velocity Tracking",
+        "python3 scripts/burn_velocity_tracker.py",
+        "configs/burn_velocity_repos.json",
+        "~/.timmy/burn-velocity/latest.json",
+        "timmy-config dashboard",
+        "type=issues",
+        "velocity_drop",
+    ]
+    for snippet in required:
+        assert snippet in text