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>
This commit is contained in:
1 parent
3418738993
commit
7ed142032b
5 files changed
+382
No files matched your search
@@ -0,0 +1,88 @@
|
||||
# 005 - Radio Receipts Inline
|
||||
|
||||
## User Story
|
||||
|
||||
As the operator, I want every radio message to show who read it and who
|
||||
acknowledged it right under the message, so that I see delivery at a glance
|
||||
without a second row repeating the same text.
|
||||
|
||||
## Decisions (operator-confirmed 2026-11-13; do not re-litigate)
|
||||
|
||||
1. **Read for all, ack where it exists**: under every message of every class
|
||||
(post, call, newsletter, broadcast, mayday, pan-pan, sécurité, grant) the
|
||||
avatars of the agents that read it, from the seen marks `radio.py` keeps
|
||||
per session (`radio-seen/<sid>.json`, `news-seen/<sid>`); an avatar gets an
|
||||
acknowledged badge when that agent's receipt for the message exists.
|
||||
Rejected: an explicit acknowledgement for every class (one radio action
|
||||
per agent and message, more tokens); read only (loses the call's
|
||||
acknowledgement).
|
||||
2. **No receipt rows**: receipts no longer show as entries in the Stream, the
|
||||
radio log or an agent page; they only feed the badges. Rejected: a
|
||||
collapsed receipt row (still a second entry).
|
||||
3. **One read rule**: the hub decides "read" with the same function
|
||||
`radio.py` uses to decide what a session has seen; no second copy in the
|
||||
hub.
|
||||
4. **Sender once**: a message header names its sender exactly once (today
|
||||
"Skills Skills → Main").
|
||||
5. **Order**: the shared seen function and a new hub module for readers and
|
||||
acks may start at once; wiring into the hub view and the page starts after
|
||||
004 (radio set) is on master, since both change the radio log.
|
||||
|
||||
## Approach
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph P["🧭 0 · Preparation"]
|
||||
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
|
||||
P2 -- "✏️ corrections" --> P1
|
||||
end
|
||||
P2 -- "🤖 yes" --> A1
|
||||
subgraph A["🛰️ A · Server"]
|
||||
A1["🧩 Shared seen function, readers and acks per row"] --> A2{"🧪 Unit and integration green?"}
|
||||
A2 -- "🔴 no: fix" --> A1
|
||||
end
|
||||
A2 -- "🟢 yes, 004 on master" --> B1
|
||||
subgraph B["🖼️ B · Page"]
|
||||
B1["👥 Avatars and badges, no receipt rows, sender once"] --> 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
|
||||
|
||||
### Server
|
||||
|
||||
- [ ] Each radio row the hub serves carries `readers` (session id, name, read
|
||||
time) and `acks` (session ids), computed by the function `radio.py`
|
||||
uses for its own seen check; a unit test covers every class.
|
||||
- [ ] A receipt counts for its call when the call is served, even if the
|
||||
receipt row lies outside the served window.
|
||||
- [ ] A missing, malformed, unreadable or future-dated seen mark counts as
|
||||
not read.
|
||||
- [ ] Receipt rows are absent from the rows served to the Stream, the radio
|
||||
log and agent pages; count badges count messages without receipts.
|
||||
|
||||
### Page
|
||||
|
||||
- [ ] Under each message one avatar per reader, an acknowledged badge on
|
||||
readers with a receipt, name and read time in the avatar's title.
|
||||
- [ ] More than 8 readers collapse into "+N" with the full list on hover.
|
||||
- [ ] The e2e count of entries with the class pill "Read" is 0 in the
|
||||
Stream, the radio log and an agent page.
|
||||
- [ ] The message header shows the sender name exactly once.
|
||||
- [ ] Avatars appear on the next poll after a mark advances, without a
|
||||
reload.
|
||||
|
||||
### Tests
|
||||
|
||||
- [ ] Unit: readers and acks per class; malformed marks; receipt to call
|
||||
matching by call time; the header renders the sender once.
|
||||
- [ ] Integration: the hub state endpoint over a council fixture (posts,
|
||||
calls, broadcasts, receipts, seen marks) returns readers and acks and
|
||||
no receipt rows.
|
||||
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: a call with two
|
||||
readers and one receipt shows two avatars, one with the badge, no
|
||||
"Read" entry and the sender once; screenshots for the checkpoint.
|
||||
@@ -0,0 +1,107 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,90 @@
|
||||
# 007 - Resources View
|
||||
|
||||
## User Story
|
||||
|
||||
As the operator, I want all hardware load in one chart, the tokens in a
|
||||
second, every series switchable and a combined view with the burnup, so that
|
||||
I see in one place how load, token spend and progress relate.
|
||||
|
||||
## Decisions (operator-confirmed 2026-11-13; do not re-litigate)
|
||||
|
||||
1. **Two rows**: Hardware (disk per mount, CPU, RAM, swap, GPU and VRAM per
|
||||
device as lines on one % axis; zones and queue marks stay) and Tokens
|
||||
(per-agent stacked bars per interval, with a switch to accumulated:
|
||||
per-agent running sums). Rejected: one row per resource as today.
|
||||
2. **Legend chips**: every series has a chip in its legend that hides or
|
||||
shows it, all shown by default; one shared helper serves 006 and 008 too.
|
||||
3. **Combined mode**: a switch overlays hardware % (left axis), tokens (right
|
||||
axis, per interval or accumulated as the tokens switch says) and burnup
|
||||
(done and scope, scaled to % of the largest scope in the window, left
|
||||
axis) in one chart; every series deselectable, all on by default.
|
||||
4. **Unsigned view store**: `/api/view` on the hub keeps view state
|
||||
server-side (chips, switches, modes, the burndown overlays of 006 and the
|
||||
Home pins of 008), the same in every browser, without a passkey because it
|
||||
grants nothing; strict schema covering all three requirements, a 64 KiB
|
||||
cap, unknown keys refused. Rejected: signed hub settings (a passkey per
|
||||
click); per-browser localStorage (no shared layout).
|
||||
5. **Window**: both rows and the combined chart follow the existing range
|
||||
control.
|
||||
|
||||
## Approach
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph P["🧭 0 · Preparation"]
|
||||
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
|
||||
P2 -- "✏️ corrections" --> P1
|
||||
end
|
||||
P2 -- "🤖 yes" --> A1
|
||||
subgraph A["🗄️ A · View store and chips"]
|
||||
A1["🧩 /api/view, legend chip helper"] --> A2{"🧪 Unit and integration green?"}
|
||||
A2 -- "🔴 no: fix" --> A1
|
||||
end
|
||||
A2 -- "🟢 yes" --> B1
|
||||
subgraph B["📊 B · Charts"]
|
||||
B1["🖥️ Hardware row, 🪙 tokens row, 🔀 combined mode"] --> 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
|
||||
|
||||
### View store
|
||||
|
||||
- [ ] A GET and PUT of `/api/view` round-trip; a malformed body, an unknown
|
||||
key or more than 64 KiB answers 400 and stores nothing.
|
||||
- [ ] A PUT needs no passkey and leaves the signed settings file
|
||||
byte-identical.
|
||||
- [ ] The store is written atomically with mode 0600 and survives a hub
|
||||
restart.
|
||||
|
||||
### Hardware
|
||||
|
||||
- [ ] One SVG with a line for every disk mount, CPU, RAM, swap, every GPU and
|
||||
its VRAM; normal mode shows exactly 2 charts.
|
||||
- [ ] Hiding a line's chip removes its path, and the state persists through
|
||||
`/api/view`.
|
||||
|
||||
### Tokens
|
||||
|
||||
- [ ] Per-interval bars as today; the accumulated switch draws per-agent
|
||||
running sums that never decrease (unit test on the series function).
|
||||
- [ ] Agent chips hide and show agents.
|
||||
|
||||
### Combined
|
||||
|
||||
- [ ] The combined switch replaces both charts with one holding hardware,
|
||||
tokens and burnup series, all on by default, each deselectable.
|
||||
- [ ] Burnup is scaled as decision 3 says (unit test).
|
||||
|
||||
### Tests
|
||||
|
||||
- [ ] Unit: series builders (hardware merge, accumulation, burnup scaling);
|
||||
view store validation.
|
||||
- [ ] Integration: the hub serves `/api/view` and the resources state;
|
||||
persistence across a restart.
|
||||
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: two charts, chips
|
||||
toggle and persist, combined mode; screenshots for the checkpoint.
|
||||
@@ -0,0 +1,93 @@
|
||||
# 008 - Home Dashboard
|
||||
|
||||
## User Story
|
||||
|
||||
As the operator, I want to star any panel or item of the hub and arrange the
|
||||
starred ones on a Home tab, so that I get my own overview of what matters to
|
||||
me.
|
||||
|
||||
## Decisions (operator-confirmed 2026-11-13; do not re-litigate)
|
||||
|
||||
1. **Home tab**: a new first tab left of Stream (route `#home`); it becomes
|
||||
the start tab once at least one pin exists, otherwise Stream stays the
|
||||
start; an explicit hash wins.
|
||||
2. **Star everywhere**: a star button on every panel (each chart, the
|
||||
stream, the radio log, kanban, gantt, burndown, task list, RASCI,
|
||||
ancestry, 3D, the agents list) and on every single item (message, task,
|
||||
artifact, agent card); pressing it again unpins. Rejected: panels only;
|
||||
panels and agent cards only.
|
||||
3. **Panel registry**: every pinnable panel and item kind registers an id, a
|
||||
title and a render function that takes the tile size; Home renders tiles
|
||||
through it, live with the same data as the source view. Rejected: Home as
|
||||
saved route views (views are not built for small cells and share page
|
||||
state).
|
||||
4. **Grid**: a classic 12-column CSS grid; a tile resizes from 1 to 12
|
||||
columns wide and 1 to 12 rows high by a handle and reorders by drag and by
|
||||
the arrow keys while focused; no layout library. Rejected: gridstack.js (a
|
||||
new dependency for what CSS grid does).
|
||||
5. **Gone items**: a tile whose item no longer exists shows "gone" with an
|
||||
unpin button; it is never removed silently.
|
||||
6. **Persistence**: pins, sizes and order live in the unsigned view store of
|
||||
007, capped at 64 pins.
|
||||
7. **Order**: the registry, stars and grid may start at once against the
|
||||
view store contract of 007; persistence and e2e after 007 is 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 · Registry and stars"]
|
||||
A1["🧩 Panel registry, star on every panel and item"] --> A2{"🧪 Unit and integration green?"}
|
||||
A2 -- "🔴 no: fix" --> A1
|
||||
end
|
||||
A2 -- "🟢 yes, 007 on master" --> B1
|
||||
subgraph B["🏠 B · Home grid"]
|
||||
B1["🔲 12-column grid, resize, drag, keyboard, gone tiles, start tab"] --> 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
|
||||
|
||||
### Stars
|
||||
|
||||
- [ ] The e2e count of registered panels and items without a star is 0
|
||||
across all tabs.
|
||||
- [ ] Starring adds a tile on Home and unstarring removes it; the same
|
||||
layout shows in a second browser.
|
||||
- [ ] A 65th pin is refused with a visible message.
|
||||
|
||||
### Grid
|
||||
|
||||
- [ ] A tile spans w of 12 columns; the handle changes w from 1 to 12 and h
|
||||
from 1 to 12.
|
||||
- [ ] Drag and keyboard reorder work and persist.
|
||||
- [ ] At 390 px width every tile spans all 12 columns.
|
||||
|
||||
### Tiles
|
||||
|
||||
- [ ] A pinned chart updates on the next poll like its source view.
|
||||
- [ ] A pinned task deleted from the register shows "gone" and an unpin
|
||||
button.
|
||||
|
||||
### Start tab
|
||||
|
||||
- [ ] With no pins the hub opens on Stream, with one or more on Home; an
|
||||
explicit hash wins.
|
||||
|
||||
### Tests
|
||||
|
||||
- [ ] Unit: registry lookup, layout validation, reorder math.
|
||||
- [ ] Integration: `/api/view` accepts the pins schema and refuses an
|
||||
oversize or malformed one.
|
||||
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: star and unstar,
|
||||
resize, reorder by drag and keyboard, the gone tile, the start tab;
|
||||
screenshots for the checkpoint.
|
||||
@@ -8,3 +8,7 @@ skill defines the format.
|
||||
- [002 - Cosmos](002-cosmos.md)
|
||||
- [003 - Operator Workbench](003-operator-workbench.md)
|
||||
- [004 - Radio Set](004-radio-set.md)
|
||||
- [005 - Radio Receipts Inline](005-radio-receipts-inline.md)
|
||||
- [006 - Score Metric Overlays](006-score-metric-overlays.md)
|
||||
- [007 - Resources View](007-resources-view.md)
|
||||
- [008 - Home Dashboard](008-home-dashboard.md)
|
||||
Reference in new issue
Block a user