Files
skills/docs/requirements/006-score-metric-overlays.md
T
Kevin Veen-BirkenbachandClaude Opus 5.5 7ed142032b docs(requirements): add 005 to 008 for hub receipts, score overlays, resources view and home dashboard
005 shows readers and acks under every radio row instead of receipt rows. 006 renames the score labels to Tokens and Velocity, journals every score block, backfills it deterministically and draws each metric as a burndown overlay. 007 merges the hardware load into one chart, adds an accumulated tokens chart, a combined overlay mode and the unsigned /api/view store. 008 adds a Home tab with stars on every panel and item and a 12-column grid. All decisions operator-confirmed 2026-11-13.

🎯 Fix: 95 %
💥 Break: 1 %
💸 Cost: 100 %
⏱️ Time: 100 %
🛡️ Security: 100 %
🏆 Score: 94
🚦 Gate: ✅ 90/5, cost and time <= 100, security 100 %

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 08:51:25 +00:00

108 lines
4.8 KiB
Markdown

# 006 - Score Metric Overlays
## User Story
As the operator, I want the score of every change (Fix, Break, Tokens,
Velocity, Security, Score) recorded over time and switchable as overlays in
the burndown, so that I see how quality and cost move alongside the work.
## Decisions (operator-confirmed 2026-11-13; do not re-litigate)
1. **Labels**: 💸 Cost becomes 💸 Tokens and ⏱️ Time becomes ⏱️ Velocity in
every score output (block, line, table header) and in every skill text;
emojis and meaning stay (Tokens is the token-cost percentage, Velocity the
speed percentage against the base).
2. **One label file**: `skills/kvb-check-score/labels.json` holds per metric
key its emoji, current label and every former label (Cost, Time);
`score.py`, the backfill and the hub read it. Rejected: labels in each
script (three copies drift apart).
3. **Journal**: `score.py` appends one JSON line per `--message-block` render
to `<council root>/scores.jsonl` (time, repo remote and path, branch,
values, digest); display data only, never a gate input. Rejected: a
journal per repository (the hub would read many places).
4. **Backfill CLI**: a separate deterministic
`skills/kvb-check-score/scripts/backfill.py --repo <dir>... [--since <rev>]
[--labels <file>]` parses score blocks from commit messages through
`git log` with the label file, keyed by (remote, commit sha), idempotent (a
second run adds nothing), runnable on any host, after a reboot (the journal
lives in the RAM-backed `/tmp`) or on another PC; no model calls.
Rejected: an agent reading the history (tokens); parsing at view time in
the hub (the hub would need every repository).
5. **Overlays**: the burndown gets one switch per metric (six), all off by
default, kept in the unsigned view store of 007; an overlay draws that
metric's journal points of the branches of the tasks in the burndown's
scope on a right axis from 0 to 100 % (higher when a value exceeds 100).
Rejected: one switch for all metrics.
6. **Order**: label file, rename, journal and backfill first (Python only,
parallel to 007); the overlay wiring after 007's view store and legend
chips are on master.
## Approach
```mermaid
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes" --> A1
subgraph A["🏷️ A · Labels, journal, backfill"]
A1["🧩 labels.json, rename, journal, backfill.py"] --> A2{"🧪 Unit and integration green?"}
A2 -- "🔴 no: fix" --> A1
A2 -- "🟢 yes" --> AF{"💬 Operator feedback on output?"}
AF -- "✏️ changes" --> A1
end
AF -- "👍 fits, 007 on master" --> B1
subgraph B["📈 B · Burndown overlays"]
B1["🎚️ Six metric switches, right axis"] --> B2{"🧪 E2E green?"}
B2 -- "🔴 no: fix" --> B1
B2 -- "🟢 yes" --> BF{"💬 Operator feedback on screenshots?"}
BF -- "✏️ changes" --> B1
end
BF -- "👍 fits" --> D1["🏁 Review, commit with operator OK, hand-over"]
```
## Acceptance Criteria
### Labels
- [ ] `score.py --message-block`, the line and the table print `Tokens` and
`Velocity`, never `Cost` or `Time`.
- [ ] `grep -rnE "💸 Cost|⏱️ Time" skills/ docs/` finds nothing outside the
aliases in `labels.json`.
- [ ] A test that changes a label in a temporary `labels.json` sees it in
`score.py`'s output.
### Journal
- [ ] Each `--message-block` render appends exactly one row with the fields
of decision 3.
- [ ] A failed append prints one stderr line and keeps the exit code.
- [ ] No gate reads `scores.jsonl` (test).
### Backfill
- [ ] A fixture repository with 3 commits carrying blocks (old and new
labels) gives 3 rows on the first run and 0 on the second.
- [ ] Two runs from an empty journal give byte-identical journals.
- [ ] An unknown label is reported once per label and skipped.
- [ ] A clone at another path yields the same keys (remote plus sha).
### Overlays
- [ ] The burndown shows six metric chips, all off on first load; a chip
switched on draws its series on the right axis.
- [ ] The state survives a reload and shows the same in a second browser.
- [ ] Only rows of branches in the burndown's scope are drawn (unit test on
the series function).
### Tests
- [ ] Unit: label loading; block, line and table output; journal append;
backfill parsing of old, new and malformed blocks; overlay series
selection.
- [ ] Integration: backfill over a fixture repository, then the hub serving
the journal series for a window.
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: overlay switches,
persisted across reload and browsers; screenshots for the checkpoint.