Janady13/missionmatch / docs/archive/DIRECTIVE_AMENDMENT_5.md

1# DIRECTIVE AMENDMENT 5: THE CANDIDATE SPINE AND THE DESK DATAFLOW 2 3Applies to docs/CLAUDE_CODE_BUILD_DIRECTIVE.md. Generated 27 July 2026. 4This amendment defines the canonical dataflow through the whole 5application and adds the missing half of the recruiting desk: the 6Candidates page, reverse matching, add to job order, and job orders that 7update themselves. 8 9-------------------------------------------------------------------------------- 100. HOW TO APPLY THIS AMENDMENT 11-------------------------------------------------------------------------------- 12 131. Record "amendment 5 accepted" in BUILD_STATE with the date. 142. Section 1 becomes a permanent appendix of the directive, the canonical 15 dataflow every future feature must respect. Sections 2 through 6 amend 16 Phase 5. Section 7 amends Gate 5. Section 8 amends the Section 11 17 acceptance list. 183. All directive rules apply unchanged. The candidate scoring engine 19 stays frozen; this amendment adds entry points and lifecycle wiring, 20 never scoring code. 21 22-------------------------------------------------------------------------------- 231. THE CANONICAL DATAFLOW, PERMANENT APPENDIX 24-------------------------------------------------------------------------------- 25 26One candidate spine. One linking record. Everything hangs off it. 27 28 INTAKE CANDIDATE WORK 29 apply on fg-talent.com \ / desk pipeline 30 Import Center bulk \ / (applications) 31 screenMATCH resume > candidates table < proposal slates 32 quick add on the desk / one record per person \ screenings 33 (all paths dedupe) / all tools, same spine \ pools, searches 34 35 THE LINKING RECORD: application (candidate x requisition) 36 exactly one active application per candidate per requisition 37 38 requisition (job order, openings count, linked requirement) 39 | 40 | add to job order (from match, search, pool, or manual) 41 v 42 application: prescreen -> internal submittal -> client submittal 43 -> interview -> offer -> placed 44 or out at any stage, always with a reason code 45 | 46 | offer accepted 47 v 48 placement takes a seat under the existing FOR UPDATE seat lock 49 | 50 v 51 JOB ORDER UPDATES ITSELF 52 stage counts derive live on the order 53 last seat placed flips status to filled in the same transaction 54 remaining active applications become filled_by_another, notified 55 filled unpublishes the fg-talent.com page via the expiry sweep 56 a fall off frees the seat, reopens the order, alerts the owner, 57 and never republishes without a human confirming 58 | 59 v 60 placement end approaching -> redeployment alert -> candidate returns 61 to the available pool -> the spine loops 62 63The two match directions use the same frozen engine: a job order ranks 64candidates (sourcing, slates), and a candidate ranks open job orders 65(marketing a person). Both read through the requisition to requirement 66bridge. screenMATCH is the deep evaluation of one pairing, stored on the 67application. slateMATCH is the proposal branch off the same spine, and a 68person may sit on a slate and in a desk pipeline at once, because both 69point at the one candidate record. 70 71-------------------------------------------------------------------------------- 722. DECISIONS RECORDED 73-------------------------------------------------------------------------------- 74 751. One candidate spine. The Candidates screen in the missionMATCH command 76 center and the new desk page read the same records. Shared candidate 77 profile components are extracted into a shared frontend directory and 78 composed by both surfaces. Nothing candidate shaped is duplicated per 79 tool. 802. recruitMATCH gains a Candidates page in its navigation, gated by the 81 recruitmatch entitlement like every other desk screen. 823. Candidate search on the page is deterministic SQL: the existing hybrid 83 fusion, tsvector rank with pgvector cosine joined by reciprocal rank 84 fusion, exposed as a repository query with structured filters. The AI 85 Ask path is untouched and remains separate. 864. Reverse matching runs the frozen engine, one candidate against the 87 linked requirement of every open requisition. Orders without a linked 88 requirement appear in the results as unmatchable with a fix it link to 89 the bridge. Every computed pairing persists with score, band, engine 90 version, and computed_at, and goes stale when the requirement or the 91 candidate profile changes after computation. 925. Add to job order creates the application. Exactly one active 93 application per candidate per requisition, enforced by a partial 94 unique index over non terminal statuses. Adding a candidate whose 95 prior application on that order ended requires an explicit reopen with 96 a reason from the Amendment 2 taxonomy. 976. Applications record how they began: added_from in apply, import, 98 match, search, pool, manual, screen. When added from match, the score 99 snapshot, band, and engine version at add time are stored on the 100 application, so why this person entered this pipeline is always 101 answerable. 1027. The default stage template gains internal_submittal and 103 client_submittal as explicit stages, aligning the platform with the 104 industry standard ladder. Existing stage values are never renamed and 105 never destroyed; the template extends, historical data stands, and 106 derive.go plus analytics read the extended set. Placement type 107 templates from Amendment 2 build on this default. 1088. Job order status is a state machine: draft, open, on_hold, filled, 109 closed. Filling the last seat flips open to filled automatically 110 inside the placement transaction the seat lock already governs. A 111 fall off, meaning a placement ends early, frees the seat and flips 112 filled back to open automatically, with an alert. Manual transitions 113 remain available and every transition, automatic or manual, is 114 audited with its cause. 1159. filled_by_another is a distinct application outcome, not a rejection. 116 When an order fills, remaining active applications move there in the 117 same transaction, their candidates flagged available for other 118 orders, and owners notified through alerts. 11910. Republishing after a fall off requires a human confirm on the 120 requisition. The page never reappears on fg-talent.com silently. 121 122-------------------------------------------------------------------------------- 1233. THE CANDIDATES PAGE, IN recruitMATCH 124-------------------------------------------------------------------------------- 125 1261. Roster list with columns: name, headline or current title, clearance 127 intelligence level, top skills, location, availability, source, last 128 activity, active pipelines count, pools. Every column sortable, list 129 virtualized for size. 1302. Filters: clearance intelligence level, skills, certifications, 131 location and radius or remote, availability window, source, pool, 132 has resume, last activity age. Free text box runs the fusion query. 133 Saved searches from Amendment 2 apply here, save and rerun. 1343. Bulk actions on selected rows: add to pool, add to job order, export 135 through csvsafe. 1364. Candidate detail, composed from the shared components, tabs: 137 Profile (structured fields, clearance intelligence always labeled 138 self reported), Resumes (version list, inline viewer for the current 139 version, download, upload new version), Screenings (every screenMATCH 140 result with engine version, band, and stale badges), Pipelines (every 141 application across orders with client, order, stage, status, aging, 142 the Submissions view of the spine), Activity and Tasks (the wired 143 activities and tasks from Amendment 2), Pools. 1445. Actions on the detail: Match to open orders, Add to job order, Screen 145 against an order, Add to pool, Edit profile, Upload resume. 146 147-------------------------------------------------------------------------------- 1484. REVERSE MATCH, CANDIDATE TO OPEN ORDERS 149-------------------------------------------------------------------------------- 150 1511. Match to open orders opens a ranked list: every open requisition with 152 a linked requirement, scored by the frozen engine, showing band chip, 153 score, client, order title, openings remaining, response deadline or 154 aging, and whether this candidate already has an application there. 1552. Row actions: Add to pipeline, which creates the application with the 156 match snapshot, and Screen now, which runs the full screenMATCH 157 evaluation on the pairing and stores it. Multi select add is 158 supported. 1593. Unmatchable orders, no linked requirement, list at the bottom with a 160 link that opens the bridge flow from Amendment 2. 1614. Determinism: the same candidate and the same open orders produce the 162 same ranking every run, decimal arithmetic, no model in the loop. 163 Stale pairings recompute on open, and the persisted history of prior 164 computations is never overwritten, matching the audit posture. 165 166-------------------------------------------------------------------------------- 1675. ADD TO JOB ORDER, MECHANICS 168-------------------------------------------------------------------------------- 169 1701. One transaction: FOR UPDATE on any existing application row for the 171 pair, insert or reopen, write added_from and the snapshot when 172 present, write the activity, audit through OnTx. Eight racing adds 173 produce one application. 1742. The requisition list and detail show live stage counts, in pipeline, 175 internal submittal, client submittal, interview, offer, placed, and 176 out, derived by indexed query, plus openings remaining from 177 placements. Stat tiles click through to the filtered pipeline, per 178 the platform rule. 1793. Client detail shows its orders with the same counts, so the path the 180 request described, find a candidate, match them, add them to the 181 client's open order, is two clicks from either end and the order 182 reflects it immediately. 183 184-------------------------------------------------------------------------------- 1856. JOB ORDER SELF UPDATES 186-------------------------------------------------------------------------------- 187 1881. Filling the last seat, inside the placement transaction: requisition 189 status to filled, remaining active applications to filled_by_another 190 with notifications, publish state to unpublished with the sitemap 191 entry dropped by the sweep, all audited with cause placement_final. 1922. Fall off: a placement ending before its scheduled end frees the seat, 193 flips filled to open with cause fall_off, alerts the order owner and 194 the capture owner where linked, and leaves the page unpublished 195 pending the human republish confirm. Candidates in filled_by_another 196 on that order can be reactivated to their prior stage manually, one 197 click, with the reactivation audited. 1983. on_hold pauses publishing and SLA timers without disturbing the 199 pipeline. closed is terminal, requires a reason, and moves active 200 applications to out with reason order_closed. 201 202-------------------------------------------------------------------------------- 2037. GATE 5 ADDITIONS 204-------------------------------------------------------------------------------- 205 2061. The Candidates page finds a planted candidate by skills filter and by 207 free text through the fusion query, and the missionMATCH command 208 center Candidates screen still renders from the shared components 209 with zero regression. 2102. Reverse match on a fixture candidate returns an identical ranking 211 across repeated runs, and the engine diff against the starting commit 212 remains empty. 2133. Add to job order from the match list creates the application carrying 214 the score snapshot and added_from match. Eight racing adds of the 215 same pair produce exactly one application. A duplicate add through 216 the API is rejected. 2174. Stage counts on the requisition update as the application moves 218 through prescreen, internal submittal, client submittal, interview, 219 and offer, and each tile clicks through correctly. 2205. Placing the final seat flips the order to filled, moves the remaining 221 fixture applications to filled_by_another with alerts recorded, and 222 the fg-talent.com detail page and sitemap entry are gone. 2236. A simulated fall off frees the seat, reopens the order with an alert, 224 does not republish, and a one click reactivation restores a 225 filled_by_another candidate to their prior stage, audited. 2267. Re adding a previously rejected candidate demands a reopen reason and 227 records it. 2288. A candidate sitting on a proposal slate and in a desk pipeline 229 resolves to one candidate id everywhere it appears. 230 231-------------------------------------------------------------------------------- 2328. ACCEPTANCE ADDITIONS TO SECTION 11 233-------------------------------------------------------------------------------- 234 23533. Exactly one active application exists per candidate per requisition, 236 enforced by the database, proven by the race. 23734. Every job order status transition, automatic or manual, carries an 238 audited cause, and filled_by_another is distinguishable from 239 rejection in every report. 24035. Reverse match rankings are bit reproducible, persisted with engine 241 version, and the frozen engine remains untouched. 242