[mforce]

Closes #103. Closes #84 (batched — role/claim constants, typed SPA role union, tier-named policies). Spec §5.1–5.3, growing #73's Admin/Worker split into the real role model. This is the LAST feature slice of epic #14 before #45 (i18n).

The matrix

Role	Can
Admin (owner)	everything, incl. user management (stored name "Admin" kept — it lives in existing DBs and refresh tokens; only the concept renamed)
Manager	everything but user management — every pre-#103 admin gate (corrective, config, money, audit, export) now admits Managers
Worker (no role row)	production recording + selling, optionally narrowed to assigned flocks
Sales	customers, orders, payments — no production capture, no expenses/audit
Read-only	stock, history, reports; writes nowhere

Deferred with rationale (in GLOSSARY): Vet/Consultant (no health module to gate — it would be Read-only with a misleading name) and house-level scoping (houses aren't entities; the §5.2 assignment schema carries the nullable columns so nothing churns later).

One deliberate money-rule evolution to flag: payments move from admin-only to Owner/Manager/Sales per spec §5.1 ("Sales: customers, sales, payments"). Customer balances move with payments (they are the settlement view the Sales role works from); expenses, money reports, audit, and export stay Owner/Manager. If you want payments back behind Owner/Manager until a real Sales user exists, it's a one-line policy change.

Flock scoping (spec §5.3)

UserRoleAssignment rows narrow a worker: no rows = account-wide (grandfathering every existing #73 worker), the first row restricts to listed flocks, farm/house-wide rows grant all in the single-farm MVP. IFlockScopeGuard enforces inside the record-entry / submit / water / feed handlers (elevated roles skip; non-HTTP system callers like the demo seeder are account-level by definition). Owner-only CRUD under /users/{id}/flock-assignments, audited (User.FlockAssign/Unassign — audit filter updated).

Policy tiers (#84)

AuthPolicies.AddCluckworkPolicies() — AdminOnly (Owner+Manager, historic name kept so 30+ existing gates didn't churn), OwnerOnly, SalesAccess, SalesFlow (everyone but ReadOnly — workers keep selling, the #73 principle), ProductionWrite (Owner/Manager/Worker). Role names live once in Domain.Accounts.Roles; the SPA gets a typed Role union and role-tiered nav.

Tests (+5 → 291)

Manager corrective-tier-but-403-on-users; Sales sells/settles but 403s production+expenses+audit; ReadOnly reads-everything-writes-nothing; the full worker flock-scoping round-trip (unscoped records anywhere → assignment narrows with audit row + duplicate 409 → unassigned flock 422 FlockScope.NotAssigned on entries AND water → elevated roles unscoped → removal restores account-wide); assignment tenant isolation (cross-tenant user/flock both 404).

Runtime drill (Playwright, 8/8)

Owner: Users page shows the 5-role picker → worker row expands to assignments ("account-wide access") → assign flock → listed → remove → restored, no error state. Worker: Daily entry + Sales nav present, Users absent.

[mforce]

Review round: codex + internal adversarial-authz agent (pi endpoint down, 6th consecutive PR). An authz rewiring got the strongest gauntlet of the session — the internal agent ran an exhaustive write-route sweep (every MapPost/MapPut/MapDelete vs its effective policy) and cleared tenant isolation, token/claims handling, idempotency-vs-authz ordering, and the flock-scope mechanics. What survived both reviewers, all applied (f17de46):

1. codex High + panel — multi-role precedence incoherence: the negative-role assertions inverted for principals holding several roles (Owner+ReadOnly couldn't create an order; Manager+Sales could write production). Policies now resolve one effective role, highest wins (Owner > Manager > Sales > ReadOnly), unknown role names are denied outright (Worker = zero role claims, never "unrecognized"), and both assertion policies RequireAuthenticatedUser() so no future route gated only by them is anonymous-satisfiable. Also defuses the seeder's promote-to-Admin multi-role landmine the panel spotted.
2. panel Medium — Sales could VOID payments (best catch of the round): record a cash payment, pocket the cash, void your own record — no Owner/Manager in the loop. VoidPayment is now route-level Owner/Manager, matching every other undo in the system; record/list/balances stay Sales-tier; the SPA hides the void button from Sales.
3. codex Medium — unresolved-user guard bypass: an authenticated principal without a parseable sub now 401s in the middleware, making the scope guard's system-caller pass-through provably unreachable over HTTP (the panel had verified it unreachable with our own tokens; now it's unreachable with any token).
4. codex Medium — mismatched unassign: DELETE requires the assignment to belong to the route's user — a wrong pairing can no longer delete another worker's last assignment and silently restore them to account-wide access.
5. codex Low — test gaps: +3 tests → 294: multi-role precedence both directions + unknown-role denial; Sales records-but-cannot-void; feed-usage scoping, out-of-scope draft submit refusal, mismatched-unassign 404.

Declined with rationale: Sales/ReadOnly production reads stay open (repo-wide reads-open convention; the §5.1 matrix governs writes) and workers keep flock creation (pre-existing behavior; nothing to scope a new flock to — a scoped worker still can't record against it without an assignment).

[mforce]

Second review round — four reviewers on the post-fix head (f17de46 → aab3209): codex re-run, pi recovered (endpoint back after 6 PRs down), plus internal fix-regression and conventions agents. The fix-regression pass confirmed the first round introduced no regressions (verified EffectiveRole claim matching, the middleware 401 leaves anonymous routes untouched, unassign can't false-404, and — via docs — that group+route RequireAuthorization AND-composes, so VoidPayment's effective set is exactly Owner/Manager). The rest converged:

Applied (aab3209):

1. codex High — unknown-role read hole: my EffectiveRole comment claimed unknown roles are "denied outright", but that only held for the write policies — a principal whose only role is unrecognized could still read through the bare-auth production groups. The default authorization policy now also requires EffectiveRole != Denied, closing it across every bare-auth group at once; claims.ts mirrors it. (An unknown role is unreachable via the API — validator + Assignable block it — so this is defense-in-depth against an out-of-band DB role row, but the comment promised it, so now it's real.)
2. conventions red bug: the Users page initialized the assignment dropdown from the unfiltered flock list — an inactive first flock preselected an id the dropdown didn't show, and Assign 404'd. Fixed to the active list.
3. codex + conventions — ListUsers precedence: multi-role users were collapsed by insertion order; now highest-wins, matching EffectiveRole.
4. codex — AssignFlock validation: empty flock id → 400 validation problem, not a downstream 404.
5. codex — stale docs: the payment glossary/help still said "admin-only end to end" and the two-role model — updated to Sales-records / Owner-Manager-voids and the five-role Users screen.

Tests (+2 → 296) closing the negative-space gaps both external reviewers flagged: Manager can void a sale and a payment (the widening's whole point, previously unverified); Sales refused VoidSale; Worker refused across the full corrective+money surface; ReadOnly refused the money routes; Manager+Sales → Manager (production allowed) and Sales+ReadOnly still sells; unknown-role refused the open reads.

Verified-false / declined: pi's "duplicate-assign → 500" (the global handler maps DbUpdateException → 409) and "reports money routes may be ungated" (sales/expenses/profit each carry route-level AdminOnly).