Merge branch 'documentation/requirements-005-008-hub-views' into unify/skills-20261112-night
This commit is contained in:
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.
|
||||||
@@ -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)
|
- [002 - Cosmos](002-cosmos.md)
|
||||||
- [003 - Operator Workbench](003-operator-workbench.md)
|
- [003 - Operator Workbench](003-operator-workbench.md)
|
||||||
- [004 - Radio Set](004-radio-set.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