Janady13/missionmatch / docs/IMPROVEMENTS.md

1# IMPROVEMENTS: THE BETTERMENT BACKLOG 2 3Licensed by docs/BUILD_CONTINUATION_PROTOCOL.md Section 0 item 4 and governed by 4its Section 4. 5 6THE RULES THAT MAKE THIS FILE SAFE RATHER THAN A WISHLIST: 7 81. Ideas go HERE with a one line rationale, never straight into code. 92. Joseph triages at each Gate E. 103. Each phase may carry AT MOST ONE approved improvement item alongside its 11 scoped work. That is the entire licensed channel for unscoped betterment; 12 anything more is drift by definition. 134. Nothing in this file is a commitment. An item sitting here unbuilt is the 14 system working, not a backlog rotting. 15 16--- 17 18## APPROVED AND ALLOCATED 19 20### 3. The office format reader, xlsx and a minimal docx text path 21**Allocated to: PHASE 3. Pre approved by Joseph, 29 July 2026, as Phase 3's single 22improvement item under Section 4 item 4. Phase 3's slot is now spent.** 23 24Closing finding two of the four that held Phase 2 open. That finding is closed by 25DECISION for Phase 2, where office formats are stored, hashed and versioned with a 26graceful `unsupported_format` status and nothing is invented from them, and the reader 27itself moves here rather than being dropped. 28 29**Scope, exactly.** An xlsx reader chosen by a MEASURED Go library bake off, with the 30real Package A spreadsheet as the fixture, `05_PWS_Att4_Course_Schedule.xlsx`, sha256 31`0135bc9b4361a0a7367fe2f01fbc3064d85e29da8dcf230cfaa7957994163574`. Plus a minimal docx 32text path. Nothing beyond those two formats. 33 34**The bake off is measured, not argued**, the same way the PDF reader was chosen: each 35candidate library runs against the real fixture and the winner is picked on what it 36actually recovers, not on its README. A course schedule is a TABLE, so the existing 37table reader and its readability bar are the consumers of whatever text comes out, and 38the acceptance question is whether the schedule's rows arrive as citable rows. 39 40**It inherits the rules the PDF path learned the hard way.** A format it cannot read 41honestly is refused BY NAME rather than run through a decoder that emits plausible 42output. Any new resource limit or worker constraint is subject to the D18 standing rule, 43so `docs/evidence/phase2/functional/known-good-fixture.txt` gets rerun and matched before 44the change counts. And the reader runs behind the same provenance binding: a chunk from a 45customer's spreadsheet is born `tenant_upload` and cannot declare otherwise. 46 47### 2. Tier two, the rolling corpus harvest 48**Allocated to: PHASE 2. Pre approved by Joseph, 28 July 2026.** 49**Phase 2's slot was free when this was approved. It is now spent.** 50 51**What it is.** `sam-attachment-sync` today is TIER ONE: every tracked 52opportunity pulls its full package on first tracking and on any amendment. Tier 53two harvests a rolling corpus by a configured NAICS list, whether or not anyone 54has tracked the notice, so the corpus and the ontology grow from the market 55rather than only from what one customer happened to pursue. 56 57**What it needs that tier one does not.** 58- a configured NAICS list, not a hardcoded one 59- a STORAGE BUDGET with a ceiling, alerting through the Track H notifier before 60 the ceiling rather than after. Bubbles is at 82 percent of a 221G root disk and 61 the backups live on that same disk, so an unbounded harvest threatens the 62 backups before it threatens anything else 63- a retention rule, because a rolling corpus that only grows is a disk incident 64 with a calendar 65 66**Why it is a real improvement and not scope creep.** The learning boundary below 67says ingestion may grow the corpus, the embeddings, and the ontology suggestions. 68Tier two is the only mechanism that does that at market scale. Without it the 69ontology only ever learns the vocabulary of opportunities someone already found. 70 71**Not started.** Recorded, approved, and allocated. Tier one shipped first and 72alone, deliberately, because a harvest that runs before its budget alerting 73exists is the thing that fills the disk. 74 75--- 76 77### 1. Phone capable application shell 78**Allocated to: PHASE 5. Pre approved by Joseph, 28 July 2026.** 79 80**Rationale.** The authenticated application does not fit below about 732 pixels 81of content width, because the shell is a fixed left sidebar plus a content 82column, which is a desktop administration layout. Measured at Gate C on 28 July: 83all nine authenticated routes overflow at 320 and 390; 768, 1024, and 1440 are 84clean. 85 86**Why Phase 5 and not sooner.** Phase 5 rebuilds the desk screens anyway, so the 87shell work lands where the screens it affects are already open. Doing it earlier 88would mean touching every screen twice, and doing it mid gate would be exactly 89the unscoped drift the protocol exists to prevent. 90 91**Why this is not urgent.** The supported viewport floor for authenticated 92surfaces is 768 during the design partner program, a recorded product decision. 93Below the floor is UNSUPPORTED, not broken. Public surfaces are unaffected and 94keep the full matrix, because candidates arrive on phones. 95 96**What done looks like.** The authenticated sweep passes at 320 and 390 with no 97horizontal overflow, the sidebar collapses to a drawer under the floor, and the 98Gate C matrix for authenticated surfaces is restored to all five viewports in the 99same change that makes it true. 100 101**Guard in force until then.** No new screen may raise the shell's minimum width. 102The visual sweep measures minimum content width per route and fails a regression, 103so "we support 768" cannot decay into "we support whatever the widest screen 104happens to need". 105 106--- 107 108## PROPOSED, NOT TRIAGED 109 110Items land here from retros, from Gate D findings that are quality rather than 111correctness, and from anything noticed in passing that would be drift to act on 112immediately. 113 114### P2. Optical recognition, and character map aware PDF decoding 115Recorded 29 July 2026 as a FUTURE CANDIDATE by owner decision, closing finding one of 116the four that held Phase 2 open. Not allocated to a phase. 117 118**Finding one is closed by decision, not by this item.** A scanned or undecodable text 119layer is a GRACEFUL TERMINAL STATE: the document is stored, hashed and versioned, the 120status is `no_text_layer`, the screen explains both causes, and zero chunks are stored so 121no reviewer can cite noise. That is the settled behaviour and it is correct. 122 123**What this candidate would add** is text where there is currently none, in two distinct 124cases that are worth keeping distinct because they need different work: 125 1261. **A genuinely scanned page** has no text layer at all and needs OCR. 1272. **An undecodable text layer** HAS text and cannot be mapped to characters, because the 128 embedded font ships no usable `ToUnicode` CMap. This is the SCA wage determination's 129 case and it needs CMap aware decoding, not OCR. It is probably the cheaper of the two 130 and it is the one with a real document behind it: the wage determination is the legal 131 floor under every bill rate in a proposal. 132 133**Why it is a candidate rather than a plan.** OCR pulls in a native dependency, which 134runs straight into the cloud portability mandate, and any model based recognition would 135have to answer to the provenance rules before a single recovered word could be cited. 136Neither is a small decision and neither is Phase 2's. 137 138**The honest cost of leaving it undone**, stated so it is not rediscovered as a surprise: 139the wage determination's rate grid is not available to the product today, and the product 140says so rather than guessing. 141 142### P3. Self host the two web fonts instead of loading them from Google 143Found by the Gate C rerun, 29 July 2026, and found sideways: the ONLY finding the public 144sweep produced across two runs was a transport failure fetching a woff2 from 145fonts.gstatic.com, which did not reproduce. Chasing the flake surfaced the dependency. 146 147`frontend/index.html` preconnects to fonts.googleapis.com and fonts.gstatic.com and loads 148Inter and JetBrains Mono from them on every page load, authenticated and public alike. 149 150**Why it matters for THIS product rather than in general.** Every visitor IP and user agent 151reaches Google, and candidates arrive on the public surface, so it is their data as much as a 152customer employee's. A federal network may block the host outright, and it sits on the 153critical render path. It is also an external runtime dependency in a codebase whose stated 154mandate is no single vendor lock in and whose crypto story is built on staying inside a 155validated boundary. 156 157**Cost is small and the licence is clear.** Inter and JetBrains Mono are both OFL, so self 158hosting is permitted. Two woff2 files, a local -face block, and the two preconnect hints 159come out. It also stabilises Gate C, which is not the reason to do it but is a real benefit. 160 161**Not fixed when found**, because changing font delivery alters the render of every screen at 162once and doing that inside a gate run would invalidate the run that found it. 163 164### P1. The session endpoint answers 403 where 401 is the correct code 165Noticed during the Gate C public sweep, 28 July 2026. `GET /api/auth/session` 166returns 403 with "no session" to a visitor who is not logged in. 167`internal/modules/auth/handler.go` uses that status at four call sites. 168 169403 means authenticated but not permitted. 401 means not authenticated. This is 170the second case, so the wire is saying something slightly untrue about why the 171request failed, and any client written against the status code has to know the 172difference by convention rather than by reading it. 173 174Not fixed when found, because changing an auth status code in the middle of a 175gate run touches the auth contract and the frontend's handling of it, which is 176exactly the unscoped drift the protocol exists to prevent. The visual sweep 177allows this one response by name so the boundary is visible rather than papered 178over, and the allowance is keyed to role, status, and exact path together so it 179cannot widen quietly. 180 181Cost is small. Risk is that a client somewhere branches on 403 today. 182 183--- 184 185## DECLINED, kept so the reasoning is not relitigated 186 187Nothing yet. When an item is declined it stays here with the reason, because the 188cost of rediscovering a rejected idea is paid every time it is proposed again. 189