Merge branch 'documentation/requirements-005-008-hub-views' into unify/skills-20261112-night

This commit is contained in:
Kevin Veen-Birkenbach committed 2026-11-13 08:53:24 +00:00
commit 7ceaf8f08c
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.
+90
View File
@@ -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.
+93
View File
@@ -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.
+4
View File
@@ -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)