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>
108 lines
4.8 KiB
Markdown
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.
|