Files
skills/docs/requirements/007-resources-view.md
T
Kevin Veen-BirkenbachandClaude Opus 5.5 7ed142032b 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>
2026-11-13 08:51:25 +00:00

91 lines
3.7 KiB
Markdown

# 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.