councilroot.py resolves one durable council root for every script and migrates the old /tmp root under the held locks: a preflight conflict moves nothing, each legacy file is renamed to a staging name before it is copied so a late writer is merged by the catch-up, id-less journals merge by line multiset, a differing whole file is kept beside its namesake, and a crash marker makes install copy the skills and report. One settings-file list, managed drop-ins included, serves councilroot.py and queue.py. Tests run once on unify/skills-20261114 after the merge (operator order 2026-11-14). 🎯 Fix: 88 % 💥 Break: 7 % 💸 Tokens: 100 % ⏱️ Velocity: 100 % 🛡️ Security: 100 % 🏆 Score: 82 🚦 Gate: ⛔ fix 88 % < 90, break 7 % > 5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.9 KiB
4.9 KiB
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)
- 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).
- One label file:
skills/kvb-check-score/labels.jsonholds 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). - Journal:
score.pyappends one JSON line per--message-blockrender 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). - Backfill CLI: a separate deterministic
skills/kvb-check-score/scripts/backfill.py --repo <dir>... [--since <rev>] [--labels <file>]parses score blocks from commit messages throughgit logwith the label file, keyed by (remote, commit sha), idempotent (a second run adds nothing), runnable on any host, after a reboot (the journal lived in the RAM-backed/tmpuntil 2026-11-14 and is durable since) 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). - 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.
- 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
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 printTokensandVelocity, neverCostorTime.grep -rnE "💸 Cost|⏱️ Time" skills/ docs/finds nothing outside the aliases inlabels.jsonand the requirement documents underdocs/requirements/, which describe the rename.- A test that changes a label in a temporary
labels.jsonsees it inscore.py's output.
Journal
- Each
--message-blockrender 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.