Teams, roles and approvals, project fields, My Work (1.12.0 → 2.0.0)

.github/workflows/backend.yml

@@ -12,6 +12,11 @@ on:
     # that doesn't depend on someone opening a PR.
     - cron: "17 6 * * 2"
 
+# Least privilege by default: every job reads the repository only, and a job
+# that needs more (the coverage badge push) asks for it itself.
+permissions:
+  contents: read
+
 # A new push to a pull request supersedes the run still going for the previous
 # one. Pushes to main are never cancelled: each one publishes the coverage
 # badge, and a cancelled run would leave it behind.
@@ -71,6 +76,7 @@ jobs:
               - 'requirements*.txt'
               - 'pyproject.toml'
               - 'migrations/**'
+              - 'shared/**'
               - 'VERSION'
             ci:
               - '.github/workflows/backend.yml'

.github/workflows/docker.yml

@@ -6,6 +6,10 @@ on:
   # Every pull request, whatever its base (stacked PRs included).
   pull_request:
 
+# Least privilege: the jobs only read the repository.
+permissions:
+  contents: read
+
 # A new push to a pull request supersedes the run still going for the previous
 # one. Pushes to main are never cancelled, so every commit on main is known to
 # build.
@@ -63,6 +67,7 @@ jobs:
               - 'requirements.txt'
               - 'app/**'
               - 'frontend/**'
+              - 'shared/**'
               - 'migrations/**'
               - 'VERSION'
               - 'public/**'

.github/workflows/frontend.yml

@@ -11,6 +11,11 @@ on:
     # the audit needs a trigger that doesn't depend on someone opening a PR.
     - cron: "17 6 * * 1"
 
+# Least privilege by default: every job reads the repository only, and a job
+# that needs more (the coverage badge push) asks for it itself.
+permissions:
+  contents: read
+
 # A new push to a pull request supersedes the run still going for the previous
 # one. Pushes to main are never cancelled: each one publishes the coverage
 # badge, and a cancelled run would leave it behind.
@@ -67,6 +72,7 @@ jobs:
           filters: |
             frontend:
               - 'frontend/**'
+              - 'shared/**'
             ci:
               - '.github/workflows/frontend.yml'
 

.github/workflows/version-check.yml

@@ -4,6 +4,10 @@ on:
   pull_request:
     branches: [main]
 
+# Least privilege: the jobs only read the repository.
+permissions:
+  contents: read
+
 jobs:
   version-check:
     runs-on: ubuntu-latest

.trail/learnings/2026-10-21-rbac-approval-workflow-claude.md

@@ -0,0 +1,32 @@
+---
+title: "RBAC approvals: eleven self-booking routes through one service, 202 contract, live approvers, expiry hooks"
+author: Claude
+date: 2026-10-21
+branch: feat/rbac
+cost: { minutes: 0, tokens: 0 }
+touches:
+  - app/services/approvals.py
+  - app/routers/approvals.py
+  - app/routers/assignments.py
+  - app/routers/kanban.py
+  - app/routers/projects.py
+  - app/routers/export.py
+  - app/services/notifications.py
+  - app/websocket/broadcast.py
+  - tests/test_approvals_service.py
+  - tests/test_approvals_routes.py
+  - tests/test_project_access_routes.py
+---
+
+## Decided
+- One path: creates call `resolve_self_booking`, row writes `approvals.resolve_row_write` (pending create → its requester amends/cancels it through the request; anyone else 403 without rights, else 409); `"approval"` → `approvals.submit_request`, which commits, publishes and returns the 202 JSONResponse itself. Direct writes call `expire_overtaken` before the write and `publish` after the commit; phase/subphase/project deletes call `cancel_for_entity` right after collecting the subtree (before any ORM delete: autoflush would cascade the requests away).
+- The requester's own direct write (allow mode, or an editor on their own row) closes their open request `cancelled`, not `expired(overtaken)`; an update back to the current values withdraws the open request (200, no new request); DELETE of one's own pending create = cancel (200 `{cancelled: true}`).
+- Approvers are never stored: `approver_user_ids` is one SQL query (admins ∪ PM if `pm_approves` ∪ policy roles, the last two only when they see the site via `user_sites` or a `sites.view_all` role; requester excluded). `can_decide` is the pure per-row check; the caller's site visibility is checked separately.
+- Invalid stored values on approve (cannot happen through the API) answer 409 and leave the request pending (no close reason fits); every other re-validation failure closes `expired(<reason>)` with a 409 `{detail, status, close_reason}`.
+- Closing any request marks the approvers' unread `approval_requested` rows for it read (one UPDATE).
+
+## Tried and ruled out
+- Sequence-mocked service tests: the approve path is ~9 queries. `tests/test_approvals_service.py` uses a `FakeDB` that answers each SELECT by what it selects (entity + first column name, `with_for_update` tells the locked row from the duplicate check), so the tests pin the state machine, not the query order.
+
+## Open
+- Not implemented (not in the brief): a fresh `approval_requested` to a new PM on a `pm_id` change or to new approvers on a policy edit (edge cases #2/#10); "Apply now" (#3, frontend).

.trail/learnings/2026-10-21-rbac-todos-and-demo-approvals-claude.md

@@ -0,0 +1,29 @@
+---
+title: "RBAC todos: private rows with per-user pushes, approvals merged live, eligibility in SQL, demo pending booking"
+author: Claude
+date: 2026-10-21
+branch: feat/rbac
+cost: { minutes: 0, tokens: 0 }
+touches:
+  - app/routers/todos.py
+  - app/schemas/todo.py
+  - app/services/approvals.py
+  - app/routers/users.py
+  - app/services/tenant_data_migrations.py
+  - app/scripts/demo_data.py
+  - app/services/demo_seed.py
+  - tests/test_todos_routes.py
+  - tests/test_approvals_followups.py
+---
+
+## Decided
+- Todos are private like notifications: every query carries `assignee_id = me OR created_by = me`, strangers get 404, writes are never broadcast tenant-wide (path in `SKIP_PATTERNS`); `todo:changed {id, kind, action}` goes to assignee + creator (+ the previous assignee on a reassign) via `send_user_event`, and `todo_assigned` only when the assignee is not the actor.
+- Rights: own todo = `todos.manage_own`; someone else's = `todos.assign_others`, outright or the PM bundle on the todo's project (`user_can`); PUT checks the todo as it is and as it becomes; DELETE = creator (or the assignee once `created_by` is NULL). The project's `pm_id` is read only when the bundle can decide (`_pm_if_needed`).
+- `GET /todos/mine` merges `approvals.decidable_todo_items` (id `approval:<n>`); sort = open first, due date (none last), oldest first.
+- `to_decide` eligibility is in SQL (`approvals.decider_clause`: PM unless the action's policy has `pm_approves = false`, or the caller's role in the policy roles; admins unrestricted), so `limit` never returns a short page. The Python `can_decide` filter stays as a safety net.
+- `expire_for_requester` runs from users.py on PUT `active=0`, toggle-active off and DELETE (`deleted=True`: no notification, events `delete`); publish after the commit.
+- Data step cleanups after the request expiry: pending rows whose request is not pending are deleted, approved rows lose pointers to closed requests (one statement per assignment table).
+- Demo: roles before users; the pending row is inserted only `WHERE EXISTS` its request is still pending, then the request's `assignment_id` is filled (`AND assignment_id IS NULL`), mirroring `submit_request`'s order. The `approval_requested` notification's entity is `("approval_request", project, target)`.
+
+## Tried and ruled out
+- Proving "a page is not cut short" with mocks: impossible. `tests/test_approvals_followups.py` runs `list_requests` against in-memory SQLite (sync Session behind a tiny async `execute` adapter; every tenant table copied into a fresh MetaData with the PostgreSQL CHECKs stripped, only the listing's tables created). Reuse that pattern when a query's semantics, not its shape, needs a test.

.trail/learnings/2026-10-21-rbac-visible-sites-scope-reads-and-writes-claude.md

@@ -0,0 +1,29 @@
+---
+title: "RBAC visible sites: every read and write scoped server-side, view keys gate reads, site_links fixture serves the lookups"
+author: Claude
+date: 2026-10-21
+branch: feat/rbac
+cost: { minutes: 0, tokens: 0 }
+touches:
+  - app/services/site_access.py
+  - app/routers/projects.py
+  - app/routers/vacations.py
+  - app/routers/equipment.py
+  - app/routers/kanban.py
+  - app/routers/users.py
+  - tests/conftest.py
+  - tests/test_site_visibility.py
+---
+
+## Decided
+- One module, `app/services/site_access.py`: `visible_site_ids` (None = `sites.view_all`), `ensure_site_visible` (site param / body `site_id`, 403; None = site-less, view_all only), `visible_sites_clause` (list filters), `ensure_project_visible` (403, also on every project-editor/assignment/booking/Kanban write, even with `projects.edit_any`), `ensure_equipment_visible` (404), `person_is_visible` / `ensure_person_visible` (oneself or a shared visible site). view_all never queries.
+- Status codes: a site/project parameter outside = 403; reading a site, team, equipment, staff member or user outside = 404 (hide existence); writing on a person outside = 403.
+- `archived=true` without `views.archived` = 403, but `archived=all` just drops archived projects: `fetchAllProjects()` calls `archived=all`, a 403 there would break the whole Gantt load for a role without the key.
+- Vacations: `absences.view_others` = own + members of the visible sites (view_all: all); without it own only; `?siteId=` needs the key and a visible site. Superusers lost tenant-wide absence reads (deliberate).
+
+## Tried and ruled out
+- Putting the site check inside `project_access` helpers: they take no `request` (no per-request cache) and the change would ripple through every key-helper unit test. Routes call `ensure_project_visible` right before the key check instead.
+- Querying the project's/equipment's/person's sites inline in route tests: dozens of existing `side_effect` lists would shift. The lookups are module functions (`_load_project_site_id`, `_load_equipment_site_ids`, `_load_user_site_ids`) that `authed_client` patches; the `site_links` fixture places people/projects/equipment (default: at the caller's sites). Their real queries are pinned in `tests/test_visible_site_ids.py`.
+
+## Open
+- Not scoped: `GET /equipment-types` (configuration). Fix round 1 scoped custom-column values (read filter through the owning project, `ensure_project_visible` on writes), `GET /skills/user/{id}` (404) and masks other sites' project names in `/equipment/{id}/assignments` as `[External Project]`.

.trail/learnings/2026-10-21-team-filter-covers-events-and-tag-options-claude.md

@@ -0,0 +1,43 @@
+---
+title: "Team filter covers team-limited company events and the tag filter options; an event's teams are shown"
+author: Claude
+date: 2026-10-21
+branch: feat/teams
+cost: { minutes: 0, tokens: 0 }
+touches:
+  - frontend/src/utils/teams.ts
+  - frontend/src/hooks/useTeamFilter.ts
+  - frontend/src/hooks/useTagFilter.ts
+  - frontend/src/components/gantt/GanttContainer.tsx
+  - frontend/src/components/views/StaffView/StaffView.tsx
+  - frontend/src/components/views/StaffView/StaffTimelineBody.tsx
+  - frontend/src/components/views/StaffView/CompanyEventsRow.tsx
+  - frontend/src/components/views/CrossSiteView/CrossSiteView.tsx
+  - frontend/src/components/views/EquipmentView/EquipmentView.tsx
+  - frontend/src/components/views/ArchivedView/ArchivedView.tsx
+  - frontend/src/components/modals/KanbanCardModal.tsx
+  - frontend/src/components/settings/panels/CompanyEventsPanel.tsx
+  - CLAUDE.md
+  - CHANGELOG.md
+  - docs/user-guide/settings.md
+  - docs/user-guide/vacations.md
+---
+
+## Decided
+- Every read of a team-scoped entity under the current site goes through `useTeamFilter()` (or a hook built on it). The header filter only knew projects, staff rows and equipment, so a company event limited to team B stayed on every timeline and in the Staff view's Company events row under filter A, and the tag filter offered team-B tags.
+- Per-site "no team here = whole site" entities — equipment, company events, tags — share one rule, `siteScopedTeamsMatchFilter` in `utils/teams.ts` (`equipmentMatchesTeamFilter` / `eventMatchesTeamFilter` / `tagMatchesTeamFilter`): an entity passes when it has no team at this site, or when one of its teams here is selected. `noTeam` applies only to projects and staff rows; it never lets a team-limited event or tag through.
+- Views take events from `useTeamFilteredCompanyEvents()` (`{events, eventDates}`, the unfiltered store values when the filter is null, else the filtered list and a rebuilt date Set). Writes and refetches still go to `appStore.companyEvents`.
+- The tag filter narrows its **options** (`siteTags` = site tags passing `tagMatches`) but resolves projects against **every** site tag (`allSiteTags`). Resolving against the narrowed list made a visible project carrying a filtered-out tag count as having no tag of that group, so it matched "(No tag)".
+- The Kanban card dialog narrows its unassigned candidates on cards of the current site only.
+- Group-by sections (`useGanttGrouping`) and Colour-by (`useGanttColorBy`) are deliberately **not** narrowed: a section exists only when a visible project carries the tag, and hiding the section would misfile that project.
+- `VacationModal`'s staff picker is deliberately tenant-wide (admins and superusers book absences for anyone at any site).
+- An event's teams are visible: Settings → Company events has a Teams column (chips with the team colour, `title="<Team> · <Site>"`, *Whole site* when none, "N teams" when no id resolves), and the Staff view's Company events row names them after the event name for closures and plain events.
+- The Staff row's team label and the Closure badge tooltip name only the **current site's** teams (`teamIdsOnSite(event.team_ids, teamsForSite(teams, siteId))`, inactive included): an event shared with another site and limited only to teams there is whole-site here, as the filter treats it, so it shows no label and the whole-site closure tooltip. The Settings table stays cross-site (each chip's title carries its site).
+
+## Tried and ruled out
+- Narrowing `siteTags` and using it for both the dropdown and project evaluation (first cut of task 2): leaks projects into "(No tag)" selections, see above.
+
+## Watch out
+- A new view that draws company events from `appStore.companyEvents` directly reintroduces the leak; use `useTeamFilteredCompanyEvents()`.
+- `useTeamFilter.ts` imports `buildEventDateSet` through the `@/api` barrel: a test that mocks `@/api` must keep it (spread `importOriginal`).
+- The Staff view mounts several `useTeamFilteredCompanyEvents()` instances (view, timeline body, events row); they are memoised per instance, harmless, but a prop would do if it ever shows in profiles.

.trail/learnings/2026-10-21-teams-per-site-scoping-claude.md

@@ -0,0 +1,47 @@
+---
+title: "Teams per site: per-site 'no rows = whole site' scoping for tags, equipment and events; team-aware closures"
+author: Claude
+date: 2026-10-21
+branch: feat/teams
+cost: { minutes: 0, tokens: 0 }
+touches:
+  - app/models/team.py
+  - app/routers/teams.py
+  - app/services/team_rules.py
+  - app/services/tag_rules.py
+  - app/routers/projects.py
+  - app/routers/users.py
+  - app/routers/equipment.py
+  - app/routers/tags.py
+  - app/routers/sites.py
+  - app/routers/export.py
+  - migrations/add_teams.sql
+  - frontend/src/utils/teams.ts
+  - frontend/src/utils/siteClosure.ts
+  - frontend/src/hooks/useTeamFilter.ts
+  - frontend/src/stores/viewStore.ts
+  - frontend/src/components/layout/Header/TeamSelector.tsx
+  - frontend/src/components/settings/panels/TeamsPanel.tsx
+  - frontend/src/components/settings/panels/TeamScope.tsx
+  - CLAUDE.md
+  - docs/user-guide/settings.md
+  - docs/developer-guide/api-reference.md
+---
+
+## Decided
+- Data model: `teams` belongs to one site (`site_id`, name unique per site, description, colour, `active`); `team_members`, `project_teams`, `tag_teams`, `company_event_teams`, `equipment_teams` are plain M:N tables, every FK `ON DELETE CASCADE` (site delete removes teams and every link). `migrations/add_teams.sql` = `tenant_provisioner.TEAMS_SCHEMA_STATEMENTS`, also run by the tenant auto-migration.
+- Members must belong to the team's site (`load_site_members`, 400). Project teams must be at the project's site (a site-less project has none); unknown team ids on project writes are dropped silently (What-If replay), like tag ids. Users: `team_ids` strict (404), superuser only teams at their sites (403); a `site_ids` change alone prunes the memberships of removed sites.
+- Tags, equipment and company events: per site, **no team row at a site = the whole site**; rows = only those teams there. Their `team_ids` are one flat list across sites — the API checks each id is at one of the entity's sites (`ensure_teams_within_sites`), and the client restricts it to the current site's teams (`teamIdsOnSite`) before every predicate. A tag limited to teams at S applies to a project at S only if the project shares one (`tag_applies_to_project`); narrowing a tag's teams under existing projects → 409.
+- Scoping considers all teams, inactive included; only the header filter (`useTeamFilter`) offers active teams. Equipment limited solely to an inactive team is therefore hidden under any team filter.
+- Closures: a team-limited closure takes out only its teams' members at the shared sites (`getClosureOn(..., staffTeamIds, teamSiteById)`) and never shades the calendar header (`timeline.ts` treats it as a plain event); the Closure badge tooltip names the teams. A plain team-limited event shows to the whole site.
+- The header filter lives in `viewStore.teamFilters`, keyed by `tagFilterKey(siteId)` (tenant + site), absent = Whole site. viewStore's `merge` is field by field, so `teamFilters` is listed there (with `sanitizeTeamFilters`) — forgetting it silently resets the filter on every reload.
+- No team data in the session or `/auth/me`: the current user's teams come from the staff rows (`team_ids` per user–site row; `selectStaffTeamIds` unions them).
+
+## Tried and ruled out
+- Nothing substantial was tried and dropped; the per-site rule held through implementation and review.
+
+## Watch out
+- Every `getClosureOn` caller must pass the person's team set and `selectTeamSiteById`; the defaults treat a team-limited closure as whole-site, so a missed caller silently over-blocks.
+- Node 25's built-in `localStorage` shadows jsdom's: run vitest with `NODE_OPTIONS="--no-experimental-webstorage"`.
+- In the sandbox, pytest must run from a temp cwd (running it from the repo root fails with a PermissionError on the unreadable `.env`) — use the wrapper script.
+- `docs/assets/screenshots/settings-teams.png` and `team-filter.png` do not exist yet: the `settings-teams` / `team-filter` shots are registered in `scripts/screenshots/capture.py` but were not captured; add the image references to `docs/user-guide/settings.md#teams` after capturing.