docs(requirements): add 015 rates time range, 016 agents controls row, 017 legend toggle

Operator request 2026-11-17: the time range slider, replay and rate unit move
into the Rates per period panel with every rate over the chosen window and a
chip of 2 to 9 metrics (015); Priority, Day/Night and Status join the agents
view row (016); an info button hides a chart legend per Home tile and per view
(017). All three are implemented after the other open skills requirements.

🎯 Fix: 95 %
💥 Break: 1 %
💸 Tokens: 100 %
⏱️ Velocity: 100 %
🛡️ Security: 100 %
🏆 Score: 94
🚦 Gate: ✅ 90/5, tokens and velocity <= 100, security 100 %

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-17 09:45:34 +00:00
1 parent 87fbae9226
commit 27b376819c
4 files changed
+247

No files matched your search

+108
View File
@@ -0,0 +1,108 @@
# 015 - Time Range in the Rates Panel
## User Story
As the operator, I want to pick any window of the hub's history and the rate
unit in the one Rates per period panel, and read every rate over exactly that
window, so that I see how the agents worked in any past stretch with one
control instead of three.
## Decisions (operator-confirmed 2026-11-17; do not re-litigate)
1. **One panel**: the time range menu (`1 h ▾`) and the rate period select
leave the header; time range, replay and rate unit live in the Rates per
period panel the rates chip opens. The header keeps the Live line and the
chip. Rejected: keeping the header menus as shortcuts (two controls for
one value).
2. **Two-thumb slider over the whole history**: one slider spans the first
record to now with a From and a To thumb; the window moves and stretches
freely, the thumbs never cross. Presets 1 h, 6 h, 24 h, 7 d and all set
both thumbs with the end at now; arrow keys step a thumb; the exact From
and To inputs stay below the slider. The window drives the whole page as
the time range does today. Rejected: a length and an end slider (two
controls for one window), a brush on a mini timeline (most effort).
3. **Replay and Live**: Replay slides the window at its length from where it
stands to now in 48 steps of 500 ms; a click pauses. Live puts the To
thumb on now and keeps the length. A window ending at now is live.
4. **Rates over the chosen window**: a count is the sum inside the window, a
gauge its average over the window. Every unit column converts that one
window: per minute, hour, day, week, month (30 days) and year (365 days);
`all` is the sum inside the window (a gauge: its average). Example: last
7 days and unit day give the mean daily tokens of those 7 days. A window
reaching back before the first record of a kind divides by the covered
part and shows ≈, the covered span in the tooltip. Rejected: each column
its own trailing window and the scaling from the next longer window
(014 decisions 2 and 5), one value column only.
5. **Chip**: shows window and unit (`7 d · /d`) and the chosen metrics, 2 to
9 of the nine; the default stays tasks done, tokens, CPU. Where the header
lacks room the chip shows as many as fit and `+n`. Rejected: a limit of 3
or 5.
6. **Persistence**: unit and chip metrics persist in the hub settings
`rates` without a passkey, as today; the window stays page state, 1 h
live on load, as today.
7. **Timing**: implemented after every other open skills requirement.
## Approach
```mermaid
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes, after the other requirements" --> A1
subgraph A["🗄️ A · Data"]
A1["🧮 /api/rates over from and to, settings 2 to 9"] --> A2{"🧪 Unit and integration green?"}
A2 -- "🔴 no: fix" --> A1
end
A2 -- "🟢 yes" --> B1
subgraph B["🎚️ B · Panel"]
B1["🧩 Header cleanup, slider, presets, replay, unit, chip"] --> 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
### Data
- [ ] `/api/rates?from=<s>&to=<s>` returns per unit and metric the window's
sum converted to the unit, or the gauge's average; `all` holds the sum.
- [ ] A 7-day window holding 7,000,000 tokens gives `day` 1,000,000, `week`
7,000,000 and `all` 7,000,000.
- [ ] A window starting before the first record of a kind divides by the
covered seconds and returns `approx: true` with `covered` seconds.
- [ ] A gauge without a sample in the window returns null.
- [ ] `rates.metrics` accepts 2 to 9 distinct metrics; 1 or a duplicate is
refused with a 400.
### Panel
- [ ] The header holds no time range menu and no rate period select; the
Live line and the chip stay.
- [ ] The panel shows the presets, the two-thumb slider, Replay, Live, the
From and To inputs, the unit picker and the table.
- [ ] Dragging From to 9 days ago and To to 2 days ago reloads the stream,
the charts and the rates for that window, and the label names both
ends.
- [ ] Each preset sets both thumbs with the end at now.
- [ ] ArrowLeft and ArrowRight move the focused thumb one step; From never
passes To.
- [ ] Replay slides the window to now and ends live; a click pauses it.
- [ ] With 7 d and unit d the chip's tokens equal the table's `d` cell and
the window's token sum divided by 7.
- [ ] With 9 metrics chosen the chip shows every one at 1920 and `+n` at
390, and the header never grows wider than the viewport.
- [ ] Unit and metrics survive a reload; the window returns to 1 h live.
### Tests
- [ ] Unit: window sums per unit, the covered part and approx, gauge
averages over the window, the settings round trip with 2 and 9 metrics.
- [ ] Integration: the hub serves `/api/rates?from&to` from fixture files.
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: header without the
old controls, slider by mouse and keys, presets, replay to live, unit
change, the 9-metric chip; screenshots for the checkpoint.
@@ -0,0 +1,62 @@
# 016 - Agents Controls in the View Row
## User Story
As the operator, I want the Priority, Day/Night and Status controls of the
agents screen in the row of its view switcher, so that the screen spends one
row on controls and the graph gets the room.
## Decisions (operator-confirmed 2026-11-17; do not re-litigate)
1. **One row**: the controls card holds on the left the view switcher
(Orbit, Chord, Swimlane, Tree, 3D, Hierarchy) and the 3D layout tools, on
the right Priority, Day/Night and Status; the toolbar row above it goes.
Rejected: keeping the separate toolbar row.
2. **Same controls**: the three keep their menus, labels and behaviour; only
their place changes.
3. **Narrow screens**: without room for one row the right group wraps under
the switcher, aligned right, with no horizontal scroll.
4. **Timing**: implemented after every other open skills requirement.
## Approach
```mermaid
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes, after the other requirements" --> A1
subgraph A["🧭 A · Controls row"]
A1["🧩 Move the three controls into the view card"] --> A2{"🧪 E2E green?"}
A2 -- "🔴 no: fix" --> A1
A2 -- "🟢 yes" --> AF{"💬 Operator feedback on screenshots?"}
AF -- "✏️ changes" --> A1
end
AF -- "👍 fits" --> D1["🏁 Review, commit with operator OK, hand-over"]
```
## Acceptance Criteria
### Layout
- [ ] On every agents view the `.graph` holds no `.toolbar` before
`.card.controls`.
- [ ] `.card.controls` holds the View group first and Priority, Day/Night
and Status last; at 1920 and 1366 the Status menu's right edge lies
within 16 px of the card's content edge.
- [ ] At 390 the document's `scrollWidth` is at most `innerWidth` and the
three controls sit below the switcher.
### Behaviour
- [ ] Priority opens the agent order, Day/Night shows the night mode and its
actions, Status hides and shows agent states, each as before.
### Tests
- [ ] Unit: n/a: a layout change without logic.
- [ ] Integration: n/a: no server change.
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390 on Orbit, Chord,
Swimlane, Tree, 3D and Hierarchy: the row, the wrap, the three menus
open; screenshots for the checkpoint.
+74
View File
@@ -0,0 +1,74 @@
# 017 - Legend Toggle
## User Story
As the operator, I want to hide and show a chart's legend on its Home tile
and in its view, so that a small tile shows the chart instead of its legend.
## Decisions (operator-confirmed 2026-11-17; do not re-litigate)
1. **Info button**: a button with the info icon (`bi-info-circle`) and
`aria-pressed` shows or hides the legend; on a Home tile it sits left of
the Open button, in a view next to the star. Only panels whose content
holds a legend get it, among them Tasks burndown and burnup, Tokens and
Hardware resources.
2. **Per tile and per view, in the hub store**: each Home pin and each view
keeps its own state in the hub view store, shared by every browser; the
default is shown. Rejected: one global switch, a per-browser state.
3. **The chart takes the room**: a hidden legend frees its space for the
chart; series switched off in legend chips stay off while the chips are
hidden.
4. **Timing**: implemented after every other open skills requirement.
## Approach
```mermaid
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes, after the other requirements" --> A1
subgraph A["🗄️ A · State"]
A1["🧮 View store keys for tile and view legends"] --> A2{"🧪 Unit green?"}
A2 -- "🔴 no: fix" --> A1
end
A2 -- "🟢 yes" --> B1
subgraph B["ℹ️ B · Buttons"]
B1["🧩 Info button on tiles and views"] --> 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
### Button
- [ ] A DOM scan of Home and every view finds the info button exactly on
the tiles and views whose content holds a `.legend`.
- [ ] On a tile it is the head button left of Open; in a view it sits next
to the star.
- [ ] A click hides the legend and the chart's height grows; a second click
shows it again.
### State
- [ ] The state survives a reload and shows in a second browser.
- [ ] Hiding the legend on the Tokens tile leaves the Tokens view's legend
shown, and the reverse.
- [ ] With the IAM series switched off and the Tokens legend hidden, the
chart still leaves IAM out.
- [ ] The view store refuses an unknown panel key and a non-boolean value
with a 400.
### Tests
- [ ] Unit: view store validation and defaults of the legend keys.
- [ ] Integration: the hub keeps the legend state across a restart from its
view file.
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: the scan, hide and
show on a tile and in a view, persistence across a reload and a second
browser; screenshots for the checkpoint.
+3
View File
@@ -18,3 +18,6 @@ skill defines the format.
- [012 - Match Review](012-match-review.md)
- [013 - Voice Input](013-voice-input.md)
- [014 - Header Rates](014-header-rates.md)
- [015 - Time Range in the Rates Panel](015-rates-time-range.md)
- [016 - Agents Controls in the View Row](016-agents-controls-row.md)
- [017 - Legend Toggle](017-legend-toggle.md)