Kanban Board: WIP Limits, Flow Metrics and Expedite Lanes

Kanban Board: WIP Limits, Flow Metrics and Expedite Lanes

You've joined the platform team that owns Flowboard, the small service behind the engineering org's Kanban board. Last sprint's retro had two complaints: the board lets teams exceed their WIP limits, and the cycle-time numbers in the weekly report "don't match what we remember". Two features are queued behind the fixes. Every time is an integer number of minutes since the board's epoch (minute 0); week 0 is minutes 0 ... 10079, week 1 is 10080 ... 20159, and so on.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh board and returns one result per operation. Every operation is [name, ts, ...args]; ts is an integer number of minutes and never decreases from one operation to the next. Errors are returned as "error: <code>" strings, never raised. An unknown operation name returns "error: unknown operation"; a wrong number of arguments or a non-integer ts returns "error: invalid arguments".

The board. Columns, left to right: backlog, ready, in_progress, review, done. in_progress and review are *split* columns: a card sitting there is either in the doing half (just arrived) or the finished half (work done, waiting to be pulled on). WIP limits are ready 3, in_progress 4, review 2; backlog and done are unlimited.

• A new card starts in backlog at ts. card_id and title must be non-empty strings; any argument of the wrong type returns invalid arguments before anything else is checked.
• A forward move goes exactly one column to the right (invalid move otherwise, including moving to the column the card is already in). A backward move may jump to any earlier column. A card that arrives in a column, forwards or backwards, starts in its doing half and goes to the back of that column's line. Cards in done cannot move (card done).
• finish flips a card in in_progress or review to the finished half. A card can leave a split column forward only from its finished half (not finished); moving backward is always allowed.
• WIP limit: a move into a limited column is refused when the cards already in that column (both halves) number at least the limit. The code is exactly e.g. wip limit reached: in_progress 4/4. A refused operation changes nothing.
• board lists each column's cards in the order they arrived there. A card in the finished half is shown as id*.
• Cycle time = minute the card entered done minus the minute it first ever entered in_progress. Moving a card backward (even all the way to ready or backlog) never resets that start. Lead time = minute it entered done minus its creation minute.
• Throughput of week w = number of cards whose entry into done falls in [w * 10080, (w + 1) * 10080); week must be an integer >= 0.
• flow is the capacity team's load generator; its behaviour is documented in flow/bulk.py. Callers keep later ts values at or after the last minute flow used.

Worked example

[["create", 0, "A", "login page"],
 ["move", 5, "A", "ready"],
 ["move", 10, "A", "in_progress"],
 ["finish", 20, "A"],
 ["move", 30, "A", "review"],
 ["move", 40, "A", "in_progress"],
 ["finish", 45, "A"],
 ["move", 50, "A", "review"],
 ["finish", 55, "A"],
 ["move", 60, "A", "done"],
 ["cycle_time", 61, "A"],
 ["lead_time", 61, "A"]]

returns [true, true, true, true, true, true, true, true, true, true, 50, 60] — the review bounce at minute 40 does not restart the clock that began at minute 10.

Part 1 — Fix the WIP and metrics bugs (FLOW-377, FLOW-381, FLOW-390)

Goal: make the board enforce the rules above; make the reported numbers match them.

Reports from the teams:

1. "Our in_progress column had five cards on it. Two of them were sitting in the finished half waiting for review, and the board let a fifth one in."
2. "A story I bounced from Review back to In Progress shows a cycle time of 12 minutes, but it took most of the afternoon." (Another story went back to Ready and later returned; check that too.)
3. "A card finished at exactly midnight on Sunday is in the wrong week of the throughput report."

A card's *work* happening in a half is not what WIP measures; the column's slots are. Fix the code so the rules in the section above hold, including the error order in the table. The existing tests in tests/ show the current behaviour; at least one of them fails.

Example (limit of 4 in in_progress; A is finished but still holds a slot)

[["create", 1, "A", "a"], ["create", 1, "B", "b"], ["create", 1, "C", "c"], ["create", 1, "D", "d"], ["create", 1, "E", "e"],
 ["move", 2, "A", "ready"], ["move", 2, "A", "in_progress"],
 ["move", 3, "B", "ready"], ["move", 3, "B", "in_progress"],
 ["move", 4, "C", "ready"], ["move", 4, "C", "in_progress"],
 ["move", 5, "D", "ready"], ["move", 5, "D", "in_progress"],
 ["finish", 6, "A"], ["move", 7, "E", "ready"], ["move", 7, "E", "in_progress"]]

The last result is "error: wip limit reached: in_progress 4/4".

Part 2 — Blocked cards (FLOW-412)

Goal: teams want to flag cards stuck on something external, keep them from silently moving, and report how long they were stuck.

Rules

1. A card can have several blockers at once (each a non-empty string id, unique among that card's *active* blockers; an id can be reused after it was unblocked). A card is blocked while at least one blocker is active.
2. A blocked card cannot move (any direction) and cannot finish: both return card blocked. In move that check comes right after invalid move, before not finished and the WIP check. In finish it comes last, after already finished.
3. Blocked cards still occupy their WIP slot, and blocking does not change cycle or lead time.
4. blocked_time is the number of minutes during which the card had at least one active blocker, as of the operation's ts. A blocker that is still active counts up to ts. Minutes covered by several blockers at once are counted once. Time spent before a card is blocked or after it is unblocked does not count.
5. board labels get a ! after the card id (after * if both apply): A*!.

Example

[["create", 0, "A", "a"],
 ["block", 10, "A", "vendor"],
 ["block", 15, "A", "env"],
 ["unblock", 20, "A", "vendor"],
 ["move", 21, "A", "ready"],
 ["unblock", 30, "A", "env"],
 ["blocked_time", 40, "A"]]

returns [true, true, true, true, "error: card blocked", true, 20] — minutes 10 to 30 are blocked once, not 25.

Part 3 — Expedite lane and percentile reports (FLOW-430)

Goal: the release manager wants an Expedite swimlane for urgent work, per-lane metrics, and a percentile cycle-time report. This changes how WIP limits work.

Rules

1. Every card is in a lane: standard (default) or expedite. create takes an optional third argument, the lane (any other value returns invalid lane, checked after invalid arguments and before card exists). flow takes the same optional lane as a fifth argument, checked after its other arguments.
2. WIP limits now apply to standard cards only. An expedite card is never refused by a column's WIP limit, and expedite cards are not counted towards a column's standard load.
3. Instead, each limited column (ready, in_progress, review) holds at most 1 expedite card (both halves). Moving an expedite card into a column that already has one returns expedite limit reached: <column> 1/1. backlog and done are unlimited for both lanes. This check sits where the WIP check sat in the move error order.
4. New operation expedite(card_id) promotes a card to the expedite lane where it stands. Errors in order: invalid arguments, card not found, card done, already expedite, expedite limit reached: <column> 1/1 (the card's current column already has an expedite card). Promotion is one-way and frees the card's standard slot.
5. board shows expedite cards with a ^ prefix: ^A*!.
6. throughput takes an optional second argument lane ("all" (default), "standard", "expedite"). A card belongs to the lane it is in when queried. Any other value is invalid lane (checked after week).
7. report(lane) returns {"done": n, "cycle_avg": x, "lead_avg": y} over cards in done for that lane ("all" allowed). Averages are rounded half up to an integer minute; with n = 0 both are null. Invalid lane returns invalid lane.
8. percentile(lane, p) returns the nearest-rank percentile of cycle time: sort the lane's cycle times ascending, take the value at 1-based rank ceil(p * n / 100). p must be an integer from 1 to 100 (invalid arguments, checked first); then invalid lane; with no done cards no completed cards.
9. Scale: hidden tests push thousands of cards through flow in one run, across both lanes, and check the board repeatedly. The whole suite has a few seconds.

Example 1: lanes (ready holds 3 standard cards and 1 expedite card)

[["create", 1, "S1", "a"], ["create", 1, "S2", "b"], ["create", 1, "S3", "c"], ["create", 1, "S4", "d"],
 ["create", 1, "X1", "hotfix", "expedite"], ["create", 1, "X2", "hotfix 2", "expedite"],
 ["move", 2, "S1", "ready"], ["move", 2, "S2", "ready"], ["move", 2, "S3", "ready"],
 ["move", 2, "S4", "ready"], ["move", 2, "X1", "ready"], ["move", 2, "X2", "ready"]]

returns [true, true, true, true, true, true, true, true, true, "error: wip limit reached: ready 3/3", true, "error: expedite limit reached: ready 1/1"].

Example 2: percentiles

[["flow", 10, "c", 4, 20], ["percentile", 200, "all", 50], ["percentile", 200, "all", 75], ["percentile", 200, "all", 1]]

returns [4, 6, 11, 5]. flow creates c1 ... c4 with cycle times 11, 5, 12, 6; sorted they are 5, 6, 11, 12, so p50 is rank 2 (6), p75 is rank 3 (11) and p1 is rank 1 (5).

Notes

• models.py and the step sequence in bulk.py are known-good.
• You may use the AI assistant freely; you are expected to verify what it produces.
• Later parts must not break earlier ones; hidden tests re-check earlier behaviour.