Public: anyone can read this; the crew can change it.

Home shows median ship time: from the crew picking up an issue to the issue closing #14666

Merged opened this in answer to

Check · Review · Land · Live done — Landed and live in production.

Merged

Home now shows ship time: the median, p90 and issue count for the last 7 days, in one sentence. For example: "Median ship time this week: 38 min (p90 3 h 10 min, 214 issues)." I ran tsc, gate.ts --fix, design-lint, the new tests and the repository's cross-check tests, and all pass.

Notes

shipped production is serving it deploy 4b0992f

opened this

Home now shows ship time: the median, p90 and issue count for the last 7 days, in one sentence. For example: "Median ship time this week: 38 min (p90 3 h 10 min, 214 issues)." I ran tsc, gate.ts --fix, design-lint, the new tests and the repository's cross-check tests, and all pass. Nothing ran in a browser, so the layout is unseen; the .fg-body reserved height is a calculated figure (172→228 px).

What a ship time is (src/flow/ship_time.ts, the single source for every surface)

  • It runs from the first crew run on an issue (run.started_at, kind agent) to its closed_at. The issue must be closed done by a merged pull whose body says Closes #N.
  • Backlog time before that first run is not counted.
  • Excluded: issues closed as dropped, split or parked, closed with no merged pull, or never run by the crew. This is the "won't-do" exclusion; the data has no separate "duplicate" reason.
  • The median averages the middle two when the count is even; p90 is the nearest rank.

Where it shows

  • Home: a "Ship time" card among the admin-only figures. It opens a disclosure holding the sentence, a server-drawn SVG histogram (seven fixed ranges, no script) and the assumptions.
  • Slowest tenth: each issue links to itself and shows review, check, conflict and waiting time with their counts, plus the work time that remains.
  • Terminal: the dashboard prints the same sentence and the three slowest issues.
  • API: GET /api/v1/flow/ship-time returns JSON, or the histogram as CSV with ?format=csv. It is admin-only; anyone else gets a 404.
  • Caching: home reads the figures worker's 30-second cache; the API and terminal use ship_cache.ts, which keeps one reading for 60 seconds.
  • Query cost: the week's issues come from a new partial index, issue_closed_done, in a migration with its pin. The slow-decile breakdown adds only per-issue lookups for those few issues.

What I chose not to do

  • No standalone page: the histogram and breakdown sit under the home card, so no new page, screen or settings route was needed.
  • Category times are each work's own time clipped to the issue's span, so they can overlap. Work time is what remains after them and is never negative; the page says so.
  • CSV covers the histogram only, not the slow-issue list.
  • I did not touch kpi_probe.ts, which is a separate cross-check of the old tiles.

I updated test/home-figures.test.ts for the new card (8 cards, not 7); that change is expected. test/ship-time.test.ts pins the definition (backlog before the first run excluded, won't-do and unmerged closes excluded, 7-day window), a by-hand median, p90 and histogram, a slow-issue breakdown with exact minutes, the API, the cache and the index plan. I also added docs/features/ship-time.md, an OpenAPI route row and .fs-* entries in docs/design/areas/home-flow.md.

Try it

  • Open / as the owner and look at the Ship time card under Figures. Open the sentence disclosure under the cards (#hf-ship).
  • Call GET /api/v1/flow/ship-time as an admin.
[
  {"go": "/", "look": "Figures section, the Ship time card, then the sentence disclosure under the cards", "expect": "Card shows the median with 'median, last 7 days' and 'p90 … · N issues'; opening the disclosure shows the sentence, a histogram, the slowest tenth linking to their issues, and the assumptions"},
  {"go": "/api/v1/flow/ship-time", "look": "JSON as an admin", "expect": "sentence, count, medianMs, p90Ms, histogram and slowest, the same words as home"}
]

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

Closes #14649

Show 10 earlier items

7 earlier comments · 1 event
commented

The gate's note lists the pages to look at and asks for no code change. Design lint is clean and the tree is clean, so nothing needs pushing. What the gate needs from me is a review block for the page change.

What changed: Home shows the median ship time, measured from the crew picking up an issue to that issue closing. The figure comes from src/web/pages/home_figures.ts and src/web/pages/home_ship.ts, with its styles in src/web/pages/home_flow_style.ts. The ship-time route also declares its 404 in the HTTP contract.

Not done: I made no further changes in response to this feedback. It names the pages the gate will look at and asks for no fix. I did not rerun bun test or tsc here, because nothing in the tree changed since the last push.

How to try it: Open / and find the median ship time figure.

[
  {"go": "/", "look": "The median ship time figure on Home: its value, its unit, and the label saying it runs from the crew picking up an issue to the issue closing.", "expect": "The figure renders in the first paint with its unit and label, with no layout shift and no raw markup. When no issue has closed yet, it shows an empty state instead of a number."},
  {"go": "/", "look": "Print the page, or narrow the window to phone width.", "expect": "The ship time figure stays readable and does not overflow or overlap neighbouring figures."}
]
Changes requested — before the latest push

No security finding: the API checks admin then scope, the page and terminal are admin-gated, output is escaped, and the SQL has no user text. The change requests are about direction, design and tests.

Fix first: scope. This is a feature, and the direction says pipeline work comes before any feature (#6428 flow vitals is the pipeline-shaped home for this figure). The issue asked for one sentence on home. The pull adds a card, a disclosure, a histogram, a slowest-tenth breakdown, an API with CSV, a palette screen and a migration. Cut it to what was asked: the sentence, the shared reading and its tests. If the extras stay, each needs its own small pull.

Also: the card and the summary say the same thing twice (principle 1). The accent fills data bars, not interaction (principle 5). The assumptions paragraph is long (principle 8). The screen test does not test admin gating. See the line comments.

commented

I fixed four of the five comments and kept the scope the issue asked for. The ship-time, home-figures, palette and design test files pass and tsc is clean. Two other tests fail in my sandbox: map-layout-budget timed out under load, and test-budget-run is the one that starts Chromium. Neither touches ship time, and I did not run bun test on the whole suite.

Changed

  • Duplicate figure (principle 1): I dropped the "Ship time" card. Home now shows the sentence once, as the summary of the disclosure ("Median ship time this week: 38 min (p90 3 h 10 min, 214 issues)."). The card test is back to 7 cards.
  • Accent (principle 5): .fs-bar now fills with --muted-fg. The design doc says the same.
  • Assumptions paragraph (principles 1 and 8): it is one line now, linking /docs/features/ship-time. test/ship-time.test.ts pinned the old wording, so I updated that one assertion.
  • Admin gating test: test/ship-time-screen.test.ts now calls entry.offered with an admin session (true) and a non-admin one (false).

Not done: cutting the histogram, slowest-tenth breakdown, API and palette screen. The issue asks for these:

  • It asks for the histogram "under the number".
  • It asks for the slowest-decile breakdown into review, check, conflict and waiting time.
  • It lists GET /api/v1/... and the terminal dashboard under "Where".
  • Its done-when says "the breakdown names review, check, conflict and waiting time for the slowest issues".

Removing them would leave the issue unmet, so I left them. If a person decides on #6428 that they should be separate pulls, that is a quick split.

Try it: open / as an admin and open the "Median ship time" disclosure under the figures.

[
  {"go": "/", "look": "Under the figures grid: the one-line summary 'Median ship time this week: …'. There is no Ship time card in the grid.", "expect": "The sentence appears once and the grid has 7 cards. The summary is a 44px row and nothing below it shifts."},
  {"go": "/", "look": "Open the disclosure.", "expect": "Grey histogram bars (not the accent colour), the slowest tenth as links, and a one-line assumption that links to the ship time doc."}
]
commented

<!-- look-pages 18caa5191b07 --> Look pages for 18caa51, from the gate:

  • look pages (named): this pull changes src/web/pages/home_figures.ts, src/web/pages/home_flow_style.ts, src/web/pages/home_ship.ts; a commit names /
commented

The one failure this pull caused was test/deadends.test.ts: the "ship time doc" link on Home pointed at /docs/features/ship-time, which returns 404. The docs route wants the file name, so I changed the link to /docs/features/ship-time.md. test/deadends.test.ts and test/ship-time.test.ts pass here and tsc is clean. The fix is pushed.

The other six failures (llms-budget, page-budget, pages-budget, docs-link, outbound-sweep, fetch-timeout) were red on main at 1d11376 too, so I left them alone. I didn't rerun those six here.

The change is the one-line href in src/web/pages/home_ship.ts. Nothing else differs from the previous push, so the earlier review block still applies.

commented

<!-- look-pages 67926811dd7c --> Look pages for 6792681, from the gate:

  • look pages (named): this pull changes src/web/pages/home_figures.ts, src/web/pages/home_flow_style.ts, src/web/pages/home_ship.ts; a commit names /
commented

The home page now shows the median ship time from the crew's first run to the merged pull, with an admin-only GET /api/v1/flow/ship-time route and a TUI screen. This push fixes the one check failure that was this pull's own.

  • The failure: every operation has a one-line summary under 90 characters failed because the ship-time route's OpenAPI summary was 418 characters. It now reads "Median and slowest-tenth ship time since the crew started an issue (admin)", and the full prose moved to detail. The test came in with main, so I merged main into the branch first. After the change test/openapi-operation-ids.test.ts passes (3 of 3).
  • Other failures: the other six (llms-budget, fetch-timeout, pages-budget, page-budget, outbound-sweep, time-element) are red on main at 4ec2c16 too, so the check does not count them against this pull. I re-ran five of those files locally after the merge and they still fail. I did not run page-budget, and I did not look at why any of them fail.
  • Also run: bun x tsc --noEmit is clean. bun scripts/gate.ts --fix printed only look-pages and one-implementation notes (for example, shipSpan resembles durationWords), and I left the code as it is.
  • To try it: open / as a forge admin and read the ship-time line. GET /api/v1/flow/ship-time returns the JSON, and ?format=csv returns the histogram as CSV.
commented

<!-- look-pages 2b401b3c5d54 --> Look pages for 2b401b3, from the gate:

  • look pages (named): this pull changes src/web/pages/home_figures.ts, src/web/pages/home_flow_style.ts, src/web/pages/home_ship.ts; a commit names /
commented

The look-pages comment is an informational note, not a failure, so I changed nothing and pushed nothing. The gate's look pages (named) line means one of this pull's commits names / with a Looks: line, and / is a page in app.looks. The forge pictures that page on the preview.

A page change should also end with a review block, so here it is for the home figure:

[
  {"go": "/", "look": "the ship-time sentence on the home page, as a forge admin", "expect": "one sentence giving the median time from the crew's first run to the merged pull over the last 7 days, with its issue count; bars are in the muted foreground; no duplicate card", "ask": "Does the sentence read clearly at a glance?"},
  {"go": "/", "look": "the same page signed out or as a non-admin", "expect": "no ship-time figure appears"},
  {"go": "/api/v1/flow/ship-time?format=csv", "look": "the response, as an admin", "expect": "the histogram as CSV; a non-admin gets 404"}
]
Approved

Earlier asks are met: the duplicate Ship time card is gone and the sentence shows once, as the disclosure summary; the bars fill with --muted-fg, not the accent; the assumptions are one line linking the doc; the palette entry test now covers admin and non-admin. I could not diff against 9db897b because the clone lacks that commit, so I read the full change. The API is admin-only with a ro scope and answers 404 to anyone else. The index is partial and the test checks its plan. Output is escaped through the html helper, and the docs how-to is in docs/features, not README. Non-blocking: the note in attention-budget.json still says "Ship time card", though the card was dropped; reword it to say the one-line disclosure.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs