Merge pull request 'feat/wave-12-bulk-users' (#4) from feat/wave-12-bulk-users into main

Reviewed-on: #4
This commit is contained in:
2026-10-06 22:41:38 +00:00
15 changed files with 1917 additions and 68 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 128 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 112 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 97 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 78 KiB

View File

@@ -316,6 +316,17 @@ python tests/critical_reopen_check.py # BL-021 - on-hold mail reaches PM + CM
python tests/console_dialogs_check.py # BL-024 - consoles/launcher: 21 natives -> 0 17 checks
```
Wave 12 (CR-020, bulk user editing) adds these:
```bash
python tests/bulk_users_check.py # CR-020 - bulk routes, guards, audit, CSV; NO browser 61 checks
python tests/bulk_users_ui_check.py # CR-020 - selection, toolbar, CSV, typed delete at 1440/390px
```
`console_dialogs_check.py` gained section 4 (the bulk delete prompt). `tests/cdp.py`
passes `--do-not-de-elevate` on Windows so the probes start from an Administrator
shell (same change as wave 16, T16.4).
**Three probes were re-pointed at `T7.1`.** `sections_check.py` 5b drove the live
cross-frame toggle hand-off, which no longer exists; it now pins the surviving path and
the fact that an UNSAVED toggle correctly does not travel - a behaviour change, recorded

View File

@@ -662,3 +662,37 @@ deliberately deferred.
worth confirming rather than assuming).
- **Suggested wave or follow-up:** next housekeeping pass — needs Nick on
whether to delete, archive, or rewrite it as historical record.
### BL-060 — A super user is told they can change access the server then refuses
- **Found during:** T12.6 (CR-020 verification, the CSV path)
- **Where:** `server/app.py` `manage_user_problem` (the reason text), `get_user_projects` / `set_user_projects` (the rule)
- **What:** for an account that is also on a project the super user does not
administer, the refusal reason ends "You can still change their access and
role on your own projects." Neither the project-access dialog's routes nor
the CR-020 bulk project route allow that: all of them call
`require_manage_user`, which refuses the account. The bulk route mirrors the
single route on purpose (CR-020: same rules), so the words promise something
neither path does. Either the text or the rule is wrong; which one is a
product call.
- **Why not now:** changing either is out of CR-020's scope (the wave must
not widen what a super user can do), and it needs a decision.
- **Suggested wave or follow-up:** needs Nick: should a super user be able to
add or remove a shared account on their own projects? Then fix the text or
the rule, not both.
### BL-061 — The sync badge covers controls while it shows
- **Found during:** T12.6 (the wave 12 screenshots)
- **Where:** `html/project-data.js` `renderSyncBadge` (fixed bottom-right, `z-index:9998`)
- **What:** for about 2 seconds after each sync the "Everything sent to the
project" badge sits over whatever is in the bottom-right corner: a Delete
button on the User Directory at 1440px, the bulk bar's "Set permissions" at
390px. It is `pointer-events:none`, so clicks pass through, but the control is
hidden while it shows, and on the console pages there is no outbox work to
report at all.
- **Why not now:** `project-data.js` is shared by every page and owned by the
outbox work in wave 14 (T14.1 to T14.3 change this badge's states anyway).
- **Suggested wave or follow-up:** wave 14, alongside T14.1's badge changes:
do not show the badge on pages with nothing to sync, and keep it clear of
page controls.

View File

@@ -0,0 +1,355 @@
# Decisions — September 17, 2026
Three items. Like `D11`, `D15`, `D16` and `D17`, these are new scope raised after
R2 closed out (see `docs/reference/completion.md`, T9.7), not a reopening of
anything already decided there.
`CR-019` and `CR-020` get `CR` ids because they are field/product-facing feature
requests — the same kind of thing `CR-001`-`CR-018` were — not internal
engineering calls made mid-build. `D18` gets a `D` id because it is exactly that:
an internal security/architecture call, the same category as `D15` (Okta vs.
LDAPS), not a feature a user asked for.
Requested/raised by Matt Mabrey, 2026-09-17.
---
## CR-019 — Usage and activity metrics (admin console)
- **Area:** Admin Console / Monitoring
- **Priority:** proposed High — the current admin console has no reliable way to
answer "who is using this and how much," which is the same visibility gap the
original UX review found in `B4` (numbers that look authoritative but are not).
- **Source:** Matt Mabrey, 2026-09-17.
### Why this is not already built
`D5`/`T7.10` already shipped a usage-analytics feature — `html/wp-usage.js`, with
a report at `admin.js:666-699` — but it reads `localStorage`, which is scoped to
one browser. The report's own empty state says exactly this: *"No usage recorded
in this browser yet."* It cannot show who across the team is active or what they
use, because each person's activity exists only on their own machine. This is the
same class of defect `B4` named for the pipeline strip — a number that looks
authoritative but is not — just never generalized to this feature. `CR-019` is
therefore new server-side work, not a UI addition on top of what exists.
Two things already in the schema are relevant and reused rather than duplicated:
`User.last_login_at` (one timestamp, no history) and `AuditLog` (append-only,
already records business mutations — WP created, status changed, role changed —
per user, with a timestamp). Neither captures navigation or feature-open events,
which is the actual gap.
### Intent
Give admins a real, server-backed picture of who is using the suite, what parts
of it they use, and how active they are — replacing the per-browser report as
the thing anyone actually looks at.
### Decisions, made 2026-09-17
1. **Retention: indefinite.** No automatic purge of usage-event data. (Separate
from `AuditLog`'s own retention, which this does not change.)
2. **Scope: suite-wide, filterable.** Not per-project by default; the console
provides filters (date range, project, user, tool/page) rather than scoping
the data itself.
3. **Export: raw view shows real identities; export supports sanitization.**
The admin console's own tables and the CSV export both default to real
usernames — this is an internal audit tool, not a public one. But the export
also offers a "sanitize" toggle that replaces the actor with a **stable
pseudonymous id** (a per-user hash, consistent across rows and across
export runs) rather than dropping the identity field outright — so an
external system (Power BI or similar) can still group and trend "by user"
without ever receiving a real name. Flagged here as the recommended
approach rather than the only one Matt confirmed in so many words: if a
fully-anonymous (no stable id at all) export turns out to be what's
actually wanted, that is a one-line change to the same feature, raise it
in the PR rather than treating it as blocking.
4. **The old per-browser report is retired**, not kept alongside the new one.
Once `CR-019` ships, `admin.js`'s existing `usage-admin` panel (reading
`WPUsage.load(...)` per browser) is removed rather than left next to the
real report, where it would show a smaller, misleading number for whoever
happens to have it open. `html/wp-usage.js` and its two call sites
(`html/work-package-suite-app.js`'s wizard dwell-tracking, and the
creator's equivalent) are a separate question — the *recording* code can
stay or go independent of the *admin report* being retired, since dwell
events were never reliably tied to a real identity anyway. Default to
removing both unless a task finds a reason to keep the recorder; log that
reason rather than deciding it here.
### Acceptance criteria
- A new admin-only tab in `admin.html` (same role gate as the User Directory)
shows: active users over a selectable date range (day/week/month), each
user's last-active timestamp, and a breakdown of which tools/pages get
opened and how often.
- Server-side event capture, keyed to the authenticated session (real identity,
not a browser-local guess) — a new table, not an extension of `AuditLog`,
since page-open/navigation events are not business mutations and mixing them
in would make `AuditLog` noisy for its existing, narrower purpose.
- The console's filters cover date range, project, user, and tool/page, and
combine (e.g., "user X, last 30 days, field view only").
- CSV export from the console, in both raw (real usernames) and sanitized
(stable pseudonymous id per user) modes.
- Retention is indefinite; nothing in this item purges data.
- View-only, refresh-on-load. No alerting — matches how the rest of the admin
console works today; if that changes later it is new scope, not a rider on
this item.
- The old per-browser "Usage" report and its admin-console panel are removed
in the same wave, not left running alongside the new one.
- Accessible per `CLAUDE.md`'s standing `C1` rules (this is a new component,
not a legacy one — it ships accessible or it is not done, same as
everything else built since wave 7).
### Frontend/backend boundary
This needs server work, the same way `CR-004`/`CR-018`/`B4` did: a real table,
a capture endpoint, an aggregation endpoint, and an export endpoint. If a task
under this item is being built by writing to `localStorage`, it is rebuilding
the exact defect this item exists to replace — stop and say so, per
`CLAUDE.md`.
### Scheduling
New wave. Wave 10 (Okta) is merged, so this does not wait on anything.
Task breakdown: `docs/waves/wave-11.md`.
---
## CR-020 — Bulk editing of users in the admin console
- **Area:** Admin Console / User Directory
- **Priority:** proposed High — three of the four actions below touch access
control (role, project assignment, active/disabled) and the fourth is a hard
delete; getting the guardrails right matters more than getting it built fast.
- **Source:** Matt Mabrey, 2026-09-17.
### Why this is not already built
Every user-editing action in `html/users.js` today is one row, one action:
a role `<select>` per row, an activate/disable button per row, a
per-user project-membership checklist opened one user at a time, and a
per-row delete. There is no row selection in the User Directory table at all.
Server-side, every corresponding endpoint
(`/api/auth/users/{id}/active`, `/role`, `/project-role`, `/projects`, and
`DELETE /api/auth/users/{id}`) takes exactly one `user_id`. Bulk editing is new
UI (selection) and, for most actions, either a loop over the existing
single-user endpoints or new endpoints that accept a list — the task decides
which, per user count and transaction-safety needs.
**Deletion is already a hard delete today** (`delete_user`, `server/app.py:1121`
— `db.delete(u)`, not a deactivate). Bulk delete inherits that: it is not this
item's job to invent a soft-delete pattern that does not exist for the single
case, but the confirmation step around it has to be sized for the fact that a
bad multi-select now removes more than one account at once, permanently.
### Decisions, made 2026-09-17
1. **All four bulk actions are in scope:** role change, activate/disable,
project assignment (add to / remove from a project, including the
project-role), and delete.
2. **Selection works two ways:** checkboxes (select-all and individual) in the
existing User Directory table, respecting whatever filter is already
applied (role, active/disabled, project) — and a CSV upload, for a one-off
bulk operation against an external list (e.g., an offboarding list that
didn't originate in this app). Both are in scope, not a choice between them.
### Acceptance criteria
- The User Directory table gains row checkboxes and a select-all that respects
the current filter; a bulk-action toolbar appears once at least one row is
selected.
- CSV upload as an alternative to checkbox selection: a list of usernames plus
the action to apply. Validates every row, reports rejected ones by row (bad
username, user not found, actor lacks permission over that user) rather than
silently skipping them — the same validate-and-report pattern `CR-005`
established for list uploads.
- Every existing single-user guardrail carries forward unchanged: an actor
cannot include their own account in a bulk action that would disable, demote,
or delete it; a super user's bulk action is scoped to only the users and
projects `require_see_user`/`require_manage_user` already let them touch
today (a super user cannot use a bulk action to reach a user or project
outside what they manage, even via CSV); `grantable_roles` still gates which
roles an actor may assign in bulk, the same as one at a time.
- Every affected row is written to `AuditLog` individually, exactly as the
single-user endpoints do today (one `role_changed` / `user_deleted` / etc.
row per user) — a bulk action is many audited changes, not one opaque batch
entry, so per-user history stays intact and readable in isolation.
- Confirmation before applying, using the `wp-dialog` kit (`T7.9`), not a
native `confirm()`. The dialog names exactly how many users are affected and,
for delete specifically, lists the affected usernames before committing.
- Partial failure is reported, not hidden: if some rows in a batch fail (scope,
already-deleted, bad CSV row), the action applies to what it can and states
exactly which rows failed and why. It never reports success on a batch that
partly failed.
- Accessible per `C1`: real controls, keyboard-operable selection and bulk-
action toolbar, `aria-live` announcing the result.
### Recommended, not yet confirmed — raise in the PR if this is wrong
- **Bulk delete gets an extra confirmation step beyond naming the count** —
proposed as typing a confirmation phrase (e.g. the word `DELETE`) regardless
of how many rows are selected, since one bad multi-select now removes more
than one account, permanently, with no soft-delete to fall back on. This is
a recommendation, not a confirmed requirement — Matt has not signed off on
the exact mechanism.
- **Project assignment is add/remove, not replace-the-whole-list** — a bulk
"add these users to project X" or "remove these users from project X"
action, rather than a bulk action that overwrites a user's entire project
list. Proposed because add/remove is less likely to clobber project
memberships the actor didn't intend to touch; a replace-the-whole-list
version is a materially different (and riskier) feature if that turns out to
be what's actually wanted.
### Confirmed 2026-10-06 (Matt Mabrey, at the start of wave 12)
Both recommendations above are confirmed as written, and the two details
`wave-12.md` left to the build are decided:
1. **Bulk delete:** the dialog lists the affected usernames and the request is
not sent until the word `DELETE` is typed, whatever the count.
2. **Project assignment is add/remove** to or from one project at a time, with
the per-project permissions role (`ProjectMember.role`) set on add. It never
replaces a user's whole project list.
3. **Changing the table filter clears the selection** (T12.2), and the toolbar
says so, so no row hidden by the filter stays selected.
4. **The CSV holds usernames only** (T12.4). The action and its settings are
chosen in the toolbar and apply to every valid row of the file.
### Frontend/backend boundary
Selection state (which rows are checked) is fine as client-side UI state — it
is not persisted data. Everything the bulk action actually does (role,
active/disabled, project membership, delete) already requires server work
today for the single-user case, and bulk does not change that: no new
localStorage-derived state, no client-side aggregation of what changed.
### Scheduling
New wave. Independent of wave 11 (`CR-019`) — the two do not touch the same
code and can build in either order or in parallel. Task breakdown:
`docs/waves/wave-12.md`.
---
## D18 — Detecting and acting on Okta/AD deprovisioning
- **Raised by:** Matt Mabrey, 2026-09-17, in response to a direct question about
what happens when someone's AD account is removed and Okta subsequently drops
them.
- **Amends:** nothing decided, closes a gap `D15`/`D16` left unaddressed. Those
items designed how identity flows *into* this app (Okta authenticates, this
app JIT-provisions and owns roles); neither addressed what happens when an
identity is withdrawn. This app has never had any deprovisioning signal —
push or pull — since Okta went live.
### What was found
Traced through `server/auth.py` and `server/okta_auth.py`: this app has no
connection back to Okta after initial sign-in. Consequences, confirmed against
the actual code:
1. A local `users` row is never touched by anything Okta-side. `is_active`
stays `True` indefinitely unless an admin manually disables or deletes the
account through the User Directory. There is no flag distinguishing a
terminated employee's account from a current one.
2. `get_current_user` (`server/auth.py:237`) re-checks `is_active` and
`token_version` on **every request** — so a manual disable takes effect
immediately, on the very next request. The gap is not enforcement, it's
detection: nothing tells an admin to go flip that switch.
3. A session already live when someone is deprovisioned keeps working, fully,
for up to `AUTH_SESSION_HOURS` (12 hours today, `server/auth.py:63`),
because validity is checked against this app's own JWT and DB state only,
never against Okta.
4. A NEW session can't be established once Okta drops the account —
`okta_login`/`okta_callback` requires completing Okta's own sign-in, which
Okta itself refuses. The front door closes on its own; the back door (an
already-open session, and the stale local record) does not.
### Decisions, made 2026-09-17
1. **Build a scheduled sync against Okta's Management API**, not an Event Hook.
This app has, since `D15`, only ever reached out to Okta — never received
anything from it — and a polling design keeps that shape rather than
introducing a new inbound, internet-reachable endpoint with its own
signature-verification surface. Traded deliberately: this is
poll-interval-late rather than real-time, which is judged acceptable for an
HR/offboarding-driven event, not a to-the-second requirement.
2. **Revised 2026-09-23, in response to Matt's question about idle time
instead of a flat session length: sessions now slide on activity, with a
hard ceiling underneath.** A flat `AUTH_SESSION_HOURS` forces a re-check
with Okta on a fixed schedule regardless of activity; a pure idle timer
with no ceiling does the opposite — a continuously-active session would
never force a fresh Okta check on its own, which is a worse fit for the
exact threat this item exists to address (someone still clicking around
after being deprovisioned). Decided: **both**.
- `AUTH_IDLE_MINUTES` (new, default **30**): a session with no request
for this long stops being valid. Implemented as a sliding JWT expiry —
the token is reissued with a fresh `exp` on activity, throttled so the
cookie isn't rewritten on literally every request.
- `AUTH_SESSION_HOURS` (existing var, meaning changes to an **absolute
ceiling**): no session survives past this many hours from the original
sign-in, no matter how continuously active it is. Default changing from
12 to a proposed **8** — flagged as a recommendation, not confirmed.
- Both defaults, and the mechanism itself, should be sanity-checked
against the tenant's actual Okta SSO session policy — if Okta's own
session silently outlives either number, re-authentication here is
likely a fast redirect, not a real re-login screen, so these numbers
cost less than they look like they do. Confirm before treating either
as final.
3. **The sync only ever disables an account — it never re-enables one.** A
rehire showing active in Okta again does not automatically restore access;
an admin re-enabling the account is a deliberate act, consistent with
`D16`'s posture that this app never auto-grants access on its own initiative.
4. **Fail closed on the side of INACTION, not disablement.** This is the
opposite failure direction from `D16`'s login-time posture ("if Okta is
unreachable, the app is unreachable for everyone"). Here, an Okta API
error, timeout, empty response, or anything the sync can't confidently
parse must result in **no change to any account** that cycle, plus a
logged failure. A sync job that treats "couldn't reach Okta" as "nobody is
active" is a far worse outcome than a missed cycle — it would lock out the
entire org on an Okta API hiccup. This is the single most important
acceptance criterion in this item.
5. **Every auto-disable is audited individually**, same as every other
account-state change in this app: an `AuditLog` row per user, with an actor
value that's clearly the sync job and not a person (e.g.
`system:okta_sync`), so it reads correctly in the User Directory's history
and is never confused with an admin's own action.
6. **New credential required:** a read-scoped Okta API token (or an Okta
service-app OAuth2 client), separate from the `OKTA_CLIENT_ID`/
`OKTA_CLIENT_SECRET` pair used for sign-in. This needs provisioning by
whoever administers the Okta tenant — the same dependency that gated the
original OIDC rollout (D15's "security scoping reply").
### Recommended, not yet confirmed — raise in the PR if this is wrong
- **Sync interval:** proposed every 15 minutes. Frequent enough that the
detection gap is small, infrequent enough not to hammer Okta's API or need
special rate-limit handling. Not confirmed with IT/security.
- **Where the job runs:** proposed as an in-process background task inside the
existing `api` container (it already has `outbound` network access to reach
Okta, and already holds the Okta client config) rather than a new sidecar
container. The `backup` container (`docker-compose.yml`) is the existing
precedent for a scheduled-interval container in this stack, if isolation
from the `api` process is preferred instead — a reasonable alternative, not
the recommendation.
- **Admin visibility:** at minimum, an auto-disable is a normal, readable
`AuditLog` entry (visible whever admin already reviews audit history, and
naturally covered once `CR-019`'s activity view exists). Whether it should
also trigger an email/notification to admins is a genuine open question —
proposed as a fast-follow rather than blocking this item, since `D10`
already established the pattern for admin-controlled email toggles this
could reuse.
### Frontend/backend boundary
Entirely server-side and infrastructure. No new `localStorage` state, no
frontend surface beyond what already reads `is_active` and `AuditLog` today
(the User Directory, and eventually `CR-019`'s activity view).
### Scheduling
New wave, independent of wave 11 and wave 12 in the sense that nothing here is
blocked by them — but note it touches the same `is_active`/account-state
surface `CR-020`'s bulk actions touch in `server/app.py`. Not a hard
dependency; sequence commits to avoid an avoidable merge conflict, per
`CLAUDE.md`'s "one task per PR" spirit. Task breakdown: `docs/waves/wave-13.md`.

263
docs/waves/wave-12.md Normal file
View File

@@ -0,0 +1,263 @@
# Wave 12 — Bulk editing of users
**Items:** `CR-020`
**Depends on:** wave 10 merged (it is). Independent of wave 11 (`CR-019`) — no
shared files, may build in either order or in parallel.
**Decision record:** `docs/waves/decisions-2026-09-17.md` (open details
confirmed 2026-10-06, see "Confirmed 2026-10-06" in the CR-020 section)
**Branch (decided 2026-10-06):** `feat/wave-12-bulk-users`, cut from `main`
(`df20b8f`, production). Only this file and the decision record come across
from `feat/waves-11-13`, so the PR into `main` is wave 12 alone: no wave 11
code and no T13.1, which must not reach `main` before T14.1. Wave 16 is not
merged yet; it touches different functions, and whichever lands second rebases.
Six tasks, in build order.
---
### T12.1 — CR-020: bulk endpoints
- **Items:** `CR-020`
- **Depends on:** nothing (first task)
- **Blocks:** T12.2, T12.4
- **Surface:** `server/`
- **Files:** `server/app.py`
**Do:** Add bulk variants of the four existing single-user actions — role
change, active/disabled, project assignment (add/remove + project-role), and
delete. Each takes a list of `user_id`s plus the action's parameters and
applies `require_see_user`/`require_manage_user`/`grantable_roles` **per row**,
exactly as the single-user endpoint does today — a super user's bulk request
cannot reach further than their existing single-user requests can. Do not skip
the self-action guard: an actor's own account is rejected out of any batch
that would disable, demote, or delete it, same as today.
Each successful row writes its own `AuditLog` entry via `log_event`, same
action names the single endpoints already use. A row that fails is reported in
the response (user id, reason) and does not stop the rest of the batch from
being attempted.
**Do not:** invent a single opaque "bulk_action" audit entry in place of the
per-row entries. Do not build a soft-delete path for bulk delete that doesn't
exist for the single case — bulk delete stays a hard delete, matching
`delete_user` today.
**Done when:**
- [x] each of the four bulk actions is callable with a list of user ids and a
single set of parameters
- [x] a batch containing the actor's own account rejects only that row, not
the whole batch — verified for disable, demote, and delete
- [x] a super user's batch that includes a user/project outside what they
manage rejects only that row, with a stated reason
- [x] every successful row produces its own `AuditLog` entry, identical in
shape to what the single-user endpoint would have written
- [x] a batch with some failing rows still applies to the rows that succeed,
and the response lists exactly which rows failed and why
---
### T12.2 — CR-020: row selection in the User Directory table
- **Items:** `CR-020`
- **Depends on:** T12.1
- **Blocks:** T12.3
- **Surface:** `html/`
- **Files:** `html/users.js`, `html/users.html`
**Do:** Add a checkbox per row and a select-all control, respecting whatever
filter (`role`, `active`/`disabled`, project) is currently applied — select-all
selects the filtered set, not every user in the system regardless of what's
shown. A bulk-action toolbar appears once at least one row is checked and
disappears at zero.
**Done when:**
- [x] select-all selects exactly the rows currently visible under the active
filter, not the full unfiltered table
- [x] changing the filter while rows are selected does something sane and
visible (either clears the selection or keeps it explicit which rows are
still selected) — pick one and state it, don't leave it undefined
- [x] the toolbar is keyboard-reachable and only present when >=1 row is
selected
---
### T12.3 — CR-020: bulk-action toolbar
- **Items:** `CR-020`
- **Depends on:** T12.2
- **Blocks:** T12.5
- **Surface:** `html/`
- **Files:** `html/users.js`
**Do:** Wire the toolbar to T12.1's endpoints for role change, activate/
disable, and project assignment (add to / remove from a project + project-
role). Confirmation before applying uses the `wp-dialog` kit (`T7.9`) —
`wpConfirmDialog`, not a native `confirm()` — naming exactly how many users are
affected. On completion, report per-row results if anything failed (T12.1
already returns this) rather than a single success/failure toast that hides a
partial failure.
**Delete is built separately, in T12.5** — do not wire delete here.
**Done when:**
- [x] role change, activate/disable, and project assignment each work end to
end against a multi-row selection
- [x] the confirmation dialog names the exact affected count before anything is
sent
- [x] a batch with a partial failure shows which rows failed, not just an
undifferentiated error
- [x] `aria-live` announces the outcome
---
### T12.4 — CR-020: CSV upload path
- **Items:** `CR-020`
- **Depends on:** T12.1
- **Blocks:** T12.6
- **Surface:** `html/` + `server/`
- **Files:** `html/users.js`, `server/app.py`
**Do:** An upload accepting a list of usernames plus the action to apply,
following the validate-and-report pattern `CR-005` established: reject and
report bad rows (username not found, actor lacks permission over that user)
rather than silently dropping them. This is a second entry point onto the same
T12.1 endpoints, not a third implementation of the bulk logic.
**Done when:**
- [x] a CSV with a mix of valid and invalid usernames applies to the valid
rows and reports the invalid ones by row, with a reason
- [x] the same permission/self-action guards from T12.1 apply here — a CSV
cannot reach a user a checkbox-driven batch couldn't
- [x] duplicate usernames in one CSV are handled without double-applying or
erroring confusingly
---
### T12.5 — CR-020: bulk delete confirmation
- **Items:** `CR-020`
- **Depends on:** T12.3
- **Blocks:** T12.6
- **Surface:** `html/`
- **Files:** `html/users.js`
**Do:** Wire delete into the toolbar with a heavier confirmation than the other
three actions, per the decision record's recommendation: list the affected
usernames and require typing a confirmation phrase (e.g. `DELETE`) before the
request is sent, regardless of how many rows are selected. This is flagged in
the decision record as a recommendation Matt has not explicitly signed off on
— if the PR reviewer wants a lighter or heavier mechanism, that's the moment to
change it, not a reason to skip building a real confirmation now.
**Done when:**
- [x] the affected usernames are listed in the confirmation dialog before
delete is sent
- [x] the request is not sent until the confirmation phrase is typed correctly
- [x] the actor's own account, if somehow selected, is rejected with a clear
reason rather than silently included or silently dropped
---
### T12.6 — CR-020: verification
- **Items:** `CR-020`
- **Depends on:** T12.4, T12.5
- **Blocks:** nothing
- **Surface:** `html/` + `server/`
- **Files:** as touched above
**Do:** Full verification per `CLAUDE.md`: run locally, exercise bulk role
change, activate/disable, project assignment, CSV upload, and bulk delete at
390px and 1440px, before/after screenshots, smoke test, `seed_demo.py`, full
suite.
**Done when:**
- [x] all `CR-020` acceptance criteria in `decisions-2026-09-17.md` are met or
a failure is stated with a reason
- [x] screenshots committed
- [x] smoke test and `seed_demo.py` both still pass
- [x] full test suite passes
---
## Wave 12 exit criteria
- [x] all four bulk actions work against both a checkbox selection and a CSV
upload
- [x] every existing single-user guardrail (self-action, scope, grantable
roles) holds under bulk use
- [x] bulk delete requires typed confirmation and lists affected usernames
- [x] partial failures are always reported, never hidden behind a blanket
success
- [x] `CR-020` fully accounted for, no open acceptance criteria
## Verification record
Built 2026-10-06 on `feat/wave-12-bulk-users`
(from `main`, `df20b8f`), one commit per task. Run in the build sandbox (Linux,
Python 3.10, no browser).
| Check | Result |
|---|---|
| `tests/bulk_users_check.py` (new, no browser) | **61/61**: all four actions, own-row refusals, super-user scope, per-row audit in the single route's shape, partial failure, project add/remove keeping other projects and roles, CSV resolve, 403/401/422 gates |
| Same check against `main` | 7/18: the 7 single-route checks pass; every bulk check fails, because the routes do not exist there |
| Single-user routes before/after (16 calls: 200/400/403/404, as admin and super user) | **Identical** responses, audit rows and memberships against `main`. The routes now call the same `apply_*` functions as the bulk routes |
| Page logic, DOM harness (jsdom, the real `users.html` and scripts, mocked API) | **48/48**: selection, select-all over the filtered rows, filter clears selection, toolbar, confirm counts, per-row report, CSV, typed DELETE |
| Same flows, jsdom against a real server seeded by `browser_check.seed()` | **13/13**, including the CSV report texts the browser probe expects |
| `server/smoketest.py` | **27/27** |
| `server/seed_demo.py` | Seeds the demo project |
**Decisions applied (confirmed 2026-10-06):** typed `DELETE`; project assignment
is add/remove per project, with the per-project role (`ProjectMember.role`) set
on add; filter or search change clears the selection; CSV holds usernames only.
A row already in the requested state reports `unchanged` and writes no audit
row (nothing changed). An email address in the CSV resolves only when exactly
one account has it.
**Found and logged, not fixed:** BL-060, a super user's refusal reason promises
a project-access change that neither the dialog nor the bulk route allows.
**Browser probes, run 2026-10-06 on Matt's machine (Windows, Chrome 153 / Edge 154,
`.venv`), one at a time:**
| Probe | Result |
|---|---|
| `tests/bulk_users_ui_check.py` (new) | **19/19**: selection, Space on a row box, role change, super-user CSV (another job / not found / herself / duplicate, each by line), add-to-project with a role, typed DELETE, 390px bar fit, no JS errors |
| `tests/console_dialogs_check.py` | **16/16**, including the new section 4 (bulk delete prompt, natives poisoned) |
| `tests/mobile_check.py` | **24/24**, users page included |
| `tests/a11y_check.py` | **22/22**: users page 66 focusable elements, all with a visible ring; helper text 5.02:1 at worst |
| `tests/browser_check.py` | **67/71**, then re-pointed (below); **rerun after the re-point: all passed** (reported by Matt, 2026-10-06) |
**`browser_check.py` re-pointed (T12.6).** Its four failures were assertions
written against column POSITIONS: the manager table had 9 columns, and the
own-row checks read `r.cells[3]` (Permissions) and `r.cells[4]` (Project role).
CR-020's selection column is first, so the table has 10 and those indexes
landed on Username and Email. Not an app defect. The probe now expects 10
columns with the selection column first, finds the two cells by their header
name rather than their position (so the next column cannot break it the same
way), and adds one check: your own row has no selection box. Verified against
the real page in the DOM harness, then rerun in the browser: all passed.
**Screenshots** (after; the before-shots are `baseline/users-1440.png` and
`baseline/after-wave9/users-390.png`): `baseline/wave-12/users-1440.png`,
`users-1440-selected.png`, `users-390.png`, `users-390-selected.png`. Reviewed:
the bar, its four groups and the selected-row marking render as designed at
both widths; nothing scrolls sideways at 390px.
**Seen in the screenshots, not caused by wave 12, logged as BL-061:** the
pre-existing sync badge ("Everything sent to the project", `project-data.js`)
is drawn over a row's Delete button at 1440px and over "Set permissions" at
390px for about 2 seconds after a load. It is `pointer-events:none`, so it never
blocks a click, but it hides a control while it shows.
**Wave 12 closed 2026-10-06.** Every task done-when and every exit criterion
above is checked. Pushed as `feat/wave-12-bulk-users`; PR into `main` open.
Merge after wave 16 (`feat/wave-16-on-main`); both orders tested conflict-free.