diff --git a/docs/requirements/005-radio-receipts-inline.md b/docs/requirements/005-radio-receipts-inline.md new file mode 100644 index 0000000..774e07d --- /dev/null +++ b/docs/requirements/005-radio-receipts-inline.md @@ -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/.json`, `news-seen/`); 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. diff --git a/docs/requirements/006-score-metric-overlays.md b/docs/requirements/006-score-metric-overlays.md new file mode 100644 index 0000000..3055ebf --- /dev/null +++ b/docs/requirements/006-score-metric-overlays.md @@ -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 `/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 ... [--since ] + [--labels ]` 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. diff --git a/docs/requirements/007-resources-view.md b/docs/requirements/007-resources-view.md new file mode 100644 index 0000000..f7d7576 --- /dev/null +++ b/docs/requirements/007-resources-view.md @@ -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. diff --git a/docs/requirements/008-home-dashboard.md b/docs/requirements/008-home-dashboard.md new file mode 100644 index 0000000..3a5d776 --- /dev/null +++ b/docs/requirements/008-home-dashboard.md @@ -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. diff --git a/docs/requirements/README.md b/docs/requirements/README.md index 26de2a6..fe46054 100644 --- a/docs/requirements/README.md +++ b/docs/requirements/README.md @@ -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)