Files
skills/skills/kvb-check-score/scripts/score.py
T
Kevin Veen-BirkenbachandClaude Opus 5.5 5b55c39b64 feat(kvb-check-score): score journal, backfill and per-metric burndown overlays (006)
score.py names the Cost and Time metrics Tokens and Velocity from one label file and appends every scored block to a score journal in the council root. backfill.py rebuilds that journal from commit messages with its own label mapping, deterministic and idempotent, so another host can import its history. The hub serves the journal, and the Gantt burndown draws each metric as its own overlay on a right 0-100 % axis, every overlay off by default and switched by legend chips whose state the view store keeps.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 12:32:54 +00:00

307 lines
12 KiB
Python
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env python3
"""Fold fix confidence, break risk, tokens, velocity and security into one score and one gate verdict.
Args:
--fix: fix confidence in percent, 0 to 100.
--break: break risk in percent, 0 to 100.
--efficiency: tokens in percent above 0, from kvb-check-efficiency; `-` when not
measured or not relevant, `new` when the change has no base. Both count as 100
in the score.
--speed: velocity in percent above 0, from kvb-check-speed; `-` or `new` as for
--efficiency.
--security: security in percent, 0 to 100, from security.py of kvb-check-security;
`~<n>` for a value from a review by hand.
--critical: count of critical security findings.
--table: print one markdown table instead of the two lines.
--commit-table <repo>: the same table, led by the branch and staged diff stat of
that repository, then a blank line, `📁 Worktree:` and the top level path
alone in a ```text block, so it copies in one go.
--commit <sha>: with --commit-table, the diff stat of that commit instead of
the staged one, plus a commit column.
--message-block: print the commit message block instead of the two lines, one
value per line: `🎯 Fix: <f> %`, `💥 Break: <b> %`, `💸 Tokens: <c>`,
`⏱️ Velocity: <t>`, `🛡️ Security: <n> %`, `💰 Value: <n:n>` with --value only,
`🏆 Score: <n>`, `🚦 Gate: <verdict>`; values and markers as in line 1. Each
render appends one row to the score journal of journal.py; a failed append
prints one stderr line and keeps the exit code.
--value <n:n|?>: with --table, --commit-table or --message-block, a value after
the tokens one (--message-block: after security): the cost:value quotient of
tokens.py of kvb-check-efficiency, `?` when unknown. It changes neither score nor gate.
Labels and emojis come from ../labels.json.
Output:
Line 1: `🎯 fix <f> % · 💥 break <b> % · 💸 tokens <c> % · ⏱️ velocity <t> % ·
🛡️ security <n> % · 🏆 score <n>`, `–` in place of `<x> %` for `-`, `new` for `new`.
Score is fix * (100 - break) / 100 * 100 / tokens * 100 / velocity * security / 100,
capped to 0..100, rounded half up.
Line 2: the gate verdict, `✅ gate: ...`, `⛔ gate: ...` or `⚠️ gate: ...`.
Exit codes:
0 gate passed, 1 fix under 90 or break over 5, 2 usage error, a malformed
labels.json or a --commit-table repository git cannot read, one stderr line
and nothing on stdout (4 still wins with a critical finding), 3 tokens or
velocity over 100 or new, or security under 100: ask the operator before the
commit, 4 a critical security finding: do not commit.
"""
from __future__ import annotations
import argparse
import math
import re
import sys
import time
from pathlib import Path
from journal import (
LABELS,
append,
entry,
git,
git_read,
journal_path,
load_labels,
origin,
)
FIX_MIN = 90
BREAK_MAX = 5
COST_MAX = 100
SAFE = 100
DASH = "-"
NEW = "new"
ESTIMATE = "~"
COMMIT_HEADER = ("🌿 Branch", "📊 Diff stat")
WORKTREE = "📁 Worktree:"
UNKNOWN = "?"
LABEL_ERRORS = (OSError, ValueError, LookupError, TypeError, AttributeError)
QUOTIENT = re.compile(r"\d+(?:\.\d+)?:\d+(?:\.\d+)?")
SHORTSTAT = re.compile(
r"(\d+) files? changed(?:, (\d+) insertions?\(\+\))?(?:, (\d+) deletions?\(-\))?"
)
def percent(text: str) -> float:
try:
value = float(text)
except ValueError:
raise argparse.ArgumentTypeError(f"{text!r} is not a number") from None
if not 0 <= value <= 100:
raise argparse.ArgumentTypeError(f"{text!r} is outside 0..100")
return value
def cost(text: str) -> float | str:
if text in (DASH, NEW):
return text
try:
value = float(text)
except ValueError:
raise argparse.ArgumentTypeError(f"{text!r} is neither a number, {DASH!r} nor {NEW!r}") from None
if not math.isfinite(value) or value <= 0:
raise argparse.ArgumentTypeError(f"{text!r} must be a positive number")
return value
def security(text: str) -> tuple[float, str]:
mark = ESTIMATE if text.startswith(ESTIMATE) else ""
return percent(text.removeprefix(ESTIMATE)), mark
def worth(text: str) -> str:
if text == UNKNOWN or QUOTIENT.fullmatch(text):
return text
raise argparse.ArgumentTypeError(f"{text!r} is neither n:n nor {UNKNOWN!r}")
def count(text: str) -> int:
if not text.isdigit():
raise argparse.ArgumentTypeError(f"{text!r} is not a count")
return int(text)
def number(value: float) -> str:
return f"{value:g}"
def shown(value: float | str) -> str:
if value == DASH:
return "–"
if value == NEW:
return NEW
return f"{number(value)} %"
def factor(value: float | str) -> float:
return 100 / value if isinstance(value, float) else 1.0
def score(args: argparse.Namespace) -> int:
raw = (
args.fix * (100 - args.risk) / 100 * factor(args.efficiency) * factor(args.speed)
* args.security[0] / 100
)
return math.floor(min(max(raw, 0.0), 100.0) + 0.5)
def over(name: str, value: float | str) -> str | None:
if value == NEW:
return f"{name} {NEW}"
if isinstance(value, float) and value > COST_MAX:
return f"{name} {number(value)} % > {COST_MAX}"
return None
def labels(keys: set[str]) -> tuple[dict, dict]:
"""Args:
keys: the metric keys score.py measures.
Returns:
(metrics, extras) of labels.json; ValueError when it lacks one of the
keys, holds another or an entry has no string emoji and label.
"""
found = load_labels(LABELS)
metrics, extras = found["metrics"], found["extras"]
named = [*metrics.values(), extras["value"], extras["gate"]]
if set(metrics) != keys or not all(isinstance(item["emoji"], str) and isinstance(item["label"], str) for item in named):
raise ValueError(f"needs a string emoji and label for {', '.join(sorted(keys))}, value and gate")
return metrics, extras
def gate(args: argparse.Namespace, metrics: dict) -> tuple[str, str, int]:
def word(key: str) -> str:
return metrics[key]["label"].lower()
if args.critical > 0:
return "⛔", f"critical {word('security')} finding: do not commit", 4
failed = []
if args.fix < FIX_MIN:
failed.append(f"{word('fix')} {number(args.fix)} % < {FIX_MIN}")
if args.risk > BREAK_MAX:
failed.append(f"{word('break')} {number(args.risk)} % > {BREAK_MAX}")
value, mark = args.security
unsafe = f"{word('security')} {mark}{number(value)} % < {SAFE}" if value < SAFE else None
asks = [text for text in (over(word("tokens"), args.efficiency), over(word("velocity"), args.speed), unsafe) if text]
ask = f"{', '.join(asks)}: ask the operator before the commit" if asks else ""
if failed:
return "⛔", "; ".join(part for part in (", ".join(failed), ask) if part), 1
if asks:
return "⚠️", ask, 3
return "✅", f"{FIX_MIN}/{BREAK_MAX}, {word('tokens')} and {word('velocity')} <= {COST_MAX}, {word('security')} {SAFE} %", 0
def diffstat(shortstat: str) -> str:
match = SHORTSTAT.search(shortstat)
files, added, removed = (int(g or 0) for g in match.groups()) if match else (0, 0, 0)
return f"{files} file{'' if files == 1 else 's'} +{added}/-{removed}"
def commit_cells(repo: str, commit: str | None) -> tuple[list[str], list[str]]:
branch = git(repo, "branch", "--show-current") or f"detached at {git(repo, 'rev-parse', '--short', 'HEAD')}"
if commit is None:
return list(COMMIT_HEADER), [branch, diffstat(git(repo, "diff", "--cached", "--shortstat"))]
stat = git(repo, "show", "--shortstat", "--format=", commit)
return [*COMMIT_HEADER, "🔖 Commit"], [branch, diffstat(stat), git(repo, "rev-parse", "--short", commit)]
def cell(text: str) -> str:
return text.replace("|", "\\|")
def table(header: list[str], row: list[str]) -> str:
return "\n".join(
(
"| " + " | ".join(header) + " |",
"|" + " --- |" * len(header),
"| " + " | ".join(cell(value) for value in row) + " |",
)
)
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--fix", type=percent, required=True)
parser.add_argument("--break", dest="risk", type=percent, required=True)
parser.add_argument("--efficiency", type=cost, required=True)
parser.add_argument("--speed", type=cost, required=True)
parser.add_argument("--security", type=security, required=True)
parser.add_argument("--critical", type=count, required=True)
layout = parser.add_mutually_exclusive_group()
layout.add_argument("--table", action="store_true")
layout.add_argument("--commit-table", metavar="REPO")
layout.add_argument("--message-block", action="store_true")
parser.add_argument("--commit", metavar="SHA")
parser.add_argument("--value", type=worth)
args = parser.parse_args()
if args.commit and not args.commit_table:
parser.error("--commit needs --commit-table")
if args.value and not (args.table or args.commit_table or args.message_block):
parser.error("--value needs --table, --commit-table or --message-block")
total = score(args)
value, mark = args.security
measured = {
"fix": f"{number(args.fix)} %", "break": f"{number(args.risk)} %", "tokens": shown(args.efficiency),
"velocity": shown(args.speed), "security": f"{mark}{number(value)} %", "score": str(total),
}
try:
metrics, extras = labels(set(measured))
except LABEL_ERRORS as error:
print(f"score: labels {LABELS}: {error!r}", file=sys.stderr)
return 4 if args.critical > 0 else 2
emoji, verdict, code = gate(args, metrics)
verdict_cell = f"{emoji} {verdict}"
value_header = f"{extras['value']['emoji']} {extras['value']['label']}"
header = [*(f"{metric['emoji']} {metric['label']}" for metric in metrics.values()), extras["gate"]["label"]]
row = [*(measured[key] for key in metrics), verdict_cell]
if args.value:
header.insert(list(metrics).index("tokens") + 1, value_header)
row.insert(list(metrics).index("tokens") + 1, args.value)
if args.commit_table:
try:
lead, cells = commit_cells(args.commit_table, args.commit)
top = git(args.commit_table, "rev-parse", "--show-toplevel")
except LookupError as error:
print(f"score: {error}", file=sys.stderr)
return 4 if code == 4 else 2
print(table([*lead, *header], [*cells, *row]))
print(f"\n{WORKTREE}\n\n```text\n{top}\n```")
elif args.table:
print(table(header, row))
elif args.message_block:
lines = [f"{metric['emoji']} {metric['label']}: {measured[key]}" for key, metric in metrics.items()]
if args.value:
lines.insert(list(metrics).index("score"), f"{value_header}: {args.value}")
gate_label = extras["gate"]
block = "\n".join((*lines, f"{gate_label['emoji']} {gate_label['label']}: {verdict_cell}"))
print(block, flush=True)
journal(args, total, block)
else:
print(" · ".join(f"{metric['emoji']} {metric['label'].lower()} {measured[key]}" for key, metric in metrics.items()))
print(f"{emoji} gate: {verdict}")
return code
def plain(value: float | str) -> float | int | None:
if not isinstance(value, float):
return None
return int(value) if value.is_integer() else value
def journal(args: argparse.Namespace, total: int, block: str) -> None:
values = {
"fix": plain(args.fix), "break": plain(args.risk), "tokens": plain(args.efficiency),
"velocity": plain(args.speed), "security": plain(args.security[0]), "score": total,
}
path = journal_path()
try:
here = Path.cwd()
append(path, [entry(int(time.time()), origin(here), git_read(here, "branch", "--show-current") or None, None, values, block)])
except (OSError, ValueError) as error:
print(f"score: journal {path}: {getattr(error, 'strerror', None) or error}", file=sys.stderr)
if __name__ == "__main__":
sys.exit(main())