feat(customers): follow-ups — a timeline entry can say what happens next, title only on the contract, and the code-scanning alerts

[andersro93]

What

Phase 4 of the Customers roadmap ("Light CRM"), delivery C: what happens next. Plus the two things you asked for after #117: the contact association's role alias is gone (title only), and the open code-scanning alerts are fixed. Design: docs/superpowers/specs/2026-09-23-customers-follow-ups-design.md; reference: docs/customers.md → Follow-ups.

• A follow-up is part of a manual timeline entry — a due date and, optionally, an assignee (a user of the installation), on customers_timeline_entries and its revisions table (migration 00026). POST/PUT …/timeline gain followUp?: {dueOn, assigneeUserId?} | null (a full-replace PUT: omitted or null clears, and clearing clears done); dueOn may be in the future; a new assignee must exist and be active, an unchanged one is kept without being asked again. POST/DELETE …/timeline/{entryId}/follow-up/done tick and reopen: idempotent, no expected revision (a tick from a list must not conflict with a note edit), but a real change bumps current_revision and records a revision row with the actor — so who ticked it and when is the revision's own actor and time in the revisions view.
• Attention: followUpOverdue and followUpDue on /stats/attention for open follow-ups assigned to the caller or unassigned (unassigned ones are everyone's until taken), occurredAt = the due date, shaped by customers:timeline-view — a caller with customers:view alone sees none of them (never a 403), because they carry timeline-entry ids. The dashboard has the two sentences in en + nb.
• A Follow-ups page (/customers/follow-ups, nav entry under Customers with customers:timeline-view): GET /customers/follow-ups (timeline-view + view) with assignee=me|none, state=open|overdue|done|all, paging, ordered by due date; rows link to the customer; a Done tick per row with canManageTimeline.
• The timeline card gains a Follow-up section in the entry form (due date + assignee picker — the owner picker generalised into a UserPicker), a follow-up line per entry (red and "overdue" when past, struck through when done) with Done/Reopen, and the revisions panel shows each revision's follow-up state. A new canManageTimeline capability prop from the host also hides Add/Edit/Delete for readers, who used to see buttons that 403'd.
• title only (approved break, nothing live): role removed from the four contact-association schemas and every reader; the rule is title-or-roles; the contact event payload version bumps to 2; the frozen corpus is untouched and still validates (no schema sets additionalProperties: false). GET /customers/assignable-users relaxed from customers:update to customers:view so a timeline writer can pick an assignee.
• Code scanning (commit 0e0d544, verified by running CodeQL locally): the three Argon2 parameter conversions and the Seal allocation size now carry bounds the scanner can see (Seal refuses plaintext over 64 MiB with ErrTooLarge). The cookie Secure alert is a false positive — CodeQL loses the field through the cookies slice and fires its "insecure default" branch whatever the value; hard-coding Secure: true leaves it firing and breaks ~40 identity tests and the plain-http deployments docs/transport-security.md supports. Documented in code and docs; please dismiss alert Bump the "all-dependencies" group with 2 updates across multiple ecosystems #5 as false positive (I don't change the repo's security state).

Decisions made without asking (please overrule any of these)

1. A follow-up lives on a manual timeline entry, never as a separate task object and never on a generated event.
2. Done/reopen take no expected revision but are revisions of the entry; a no-change tick writes nothing and resolves no actor.
3. Attention is caller-dependent — yours or unassigned — and shaped by customers:timeline-view; for an installation where most people hold only customers:view, the dashboard's follow-up half is silent for them (the docs say so).
4. An omitted followUp on PUT clears it — the timeline PUT has always been a full replace; the form re-sends what it holds.
5. Only a new assignee is validated; an unchanged one is kept even if since disabled or deleted from the directory (shown inactive / "Unknown user").
6. GET /customers/assignable-users on customers:view — it answers display names of active users, which every customer reader already sees as the owner.
7. Dates are UTC — "today" is the server's UTC calendar day, as everywhere else in this module; a user far from UTC sees "due today" flip a few hours early or late.
8. Two filters on the page (Mine/Unassigned; Open/Overdue/Done/All) — the API's assignee=<uuid> form is reachable but the page does not offer it.
9. canManageTimeline also gates the existing Add/Edit/Delete — a consistency fix the design called out; the server always enforced it.
10. The cookie alert is not "fixed" — see above; a contortion to silence the scanner would have made the code worse.

How it was built

Spec → plan (pre-flight on the strongest model: fourteen rulings, the doneBy question decided as "the revision's own actor") → seven tasks with task reviews; fix rounds: the attention items reached customers:view-only callers (now shaped); a full-replace PUT re-validated an unchanged assignee (now exempt); the page's failed tick left a deleted entry's row on screen (now refreshes); three docs sentences the break falsified → two-seat whole-branch review (backend + contract + docs / frontend) → one fix wave per seat, scoped re-review → verification.

What the whole-branch review changed: the attention half is capped at the twenty most overdue (an installation with hundreds of open follow-ups would have flooded the card); state=all now contains state=done (both admit archived customers — all was not a superset of its own values); the docs say what happens to a departed assignee's follow-ups (kept, on nobody's list, reachable only via assignee=<uuid>; reassignment parked in the roadmap) and that "today" is the server's UTC day; the 64 MiB Seal boundary test lowers the cap through a package seam instead of allocating 250 MB; the edit form's assignee round trip is pinned by a test (dropping the seed would have silently unassigned on a note edit); clearing the date clears the assignee (a follow-up is the date) and the picker is disabled until a date is set; the Follow-ups page shows an Alert with Retry on error (a timeline-view-only caller is admitted by the nav and refused by the endpoint — now they see why).

The scoped re-review of those waves found the list operation's contract description still saying "unless state=done" — fixed in the last commit, with two tests that could not fail (a utcToday test that recomputed its own body; the twenty-cap test counting the whole attention list) made able to.

Known leftovers, parked on purpose: clearing and retyping a date in the edit form drops the assignee (the literal shape of "no date, no follow-up"; a restore-on-retype is a nicety); the dashboard card orders newest-first and shows eight, so of the twenty most overdue the least overdue reach the card — the page is where the backlog is read (documented); rows on state=all/done carry no "archived customer" marker; a departed assignee's follow-ups need the API's assignee=<uuid> form (no bucket or reassign path yet); the twenty-cap is invisible on the wire; the page's pageSize is not a route param; UserPicker re-fetches the current assignee's label per mount; the "Unknown user" sentinel is English on both locales (the owner's precedent).

Verification (local)

• On 55ac906: go generate ./..., bun run gen:client → no drift · go vet, golangci-lint run clean · go test -count=1 ./... 42 packages ok · go test -race on 4 CPUs for internal/customers/... ok · mise run frontend:check (all ten workspaces) ok. The last commit on top changes a contract description (regenerated; contract + openapi tests re-run green), two tests and a docs clause — the pre-commit hook (i18n, biome, gofmt) passed; CI runs the rest.
• corpus test green; openapi/testdata/exchanges/customers.jsonl untouched; CodeQL 2.27.1 run locally: one result left (the documented false positive).

🤖 Generated with Claude Code