Janady13/missionmatch / docs/PHASE2_DOCUMENT_TRIAL.md

1# PHASE 2 REAL DOCUMENT TRIAL: A READY TO EXECUTE CHECKLIST 2 3Written 28 July 2026. Phase 2 Gate A is OPEN pending exactly ONE blocker: a real 4solicitation package from Joseph. 5 6THIS FILE EXISTS SO THE PACKAGE ARRIVING IS THE ONLY REMAINING INPUT for the 7steps that can run today. 8 9REHEARSED END TO END AGAINST A SYNTHETIC PACKAGE, 28 July 2026, and it FAILED IN 10FOUR PLACES. That is why the rehearsal happened: a checklist nobody has ever 11executed is a plan, not a procedure, and it is cheaper to break it now than in 12front of the owner. Full record at 13docs/evidence/phase2/functional/document-trial-rehearsal.txt. The corrections are 14folded in below and the two that change the plan are stated here: 15 16 BOTH OF THOSE WERE FIXED ON 28 JULY and the checklist is updated accordingly. 17 The upload handler, cmd/opportunity-extract, cmd/opportunity-amendment-diff and 18 cmd/sam-attachment-sync all exist and are proven on staging. The PDF reader was 19 chosen by measured bake off (ledongthuc/pdf, 25 of 29 real federal PDFs usable, 20 zero panics) and real attachments now yield genuine text. STEPS 1, 2 AND 6 RUN. 21 22 WHAT IS STILL TRUE: step 3 composes notice METADATA, about 250 bytes of header 23 fields, when it runs from a tracked notice. Running it against EXTRACTED 24 DOCUMENT CHUNKS is the remaining wiring, and the trial is where that gets 25 exercised on real text for the first time. 26 27## WHERE THE PACKAGE GOES 28 29 /home/user/missionmatch/inbox/ ON MEGAMIND-AGI 30 31NOT on Bubbles. Topology rule, owner decision 29 July 2026: Bubbles carries only 32hosted site content and deployed production artifacts. Every fixture, inbox, and 33work directory lives on megamind-agi. Verify SHA256SUMS on the remote side before 34running anything below. 35 36## WHAT IS NEEDED, precisely 37 38An RFP or combined synopsis containing: 39 a PWS, SOW, or SOO 40 AT LEAST ONE amendment, because amendment handling is half of what is proven 41 ideally an attachment list, which exercises the deferred Phase 1 items 42 43Drop it anywhere and say where. No format work is needed first. 44 45## THE ORDER OF OPERATIONS, and why it is this order 46 47Section 5.1 of the directive is explicit: DETERMINISTIC EXTRACTION FIRST, before 48any model call. That ordering was already violated once and corrected in 0da4c7c, 49so it is written down here rather than trusted to memory. 50 51 STEP 1 RUNS. POST /api/opportunities/{id}/documents, multipart, gated on 52 opportunity.manage. Upload through the real intake path, never a 53 database insert: an insert would skip the allowlist, the size cap, the 54 malware hook, and the sha256 dedupe, which are the four things this 55 step exists to prove. 56 Proves: sha256 duplicate detection, the file type allowlist, the size 57 cap, extraction_status pending, and that the malware scan hook sits 58 between upload and pending. 59 Expect: opportunity_documents row, provenance BORN tenant_upload by 60 migration 0081, which nothing in the app can override. 61 ALREADY PROVEN by the rehearsal, directly against the table: an insert 62 DECLARING public_cache was born tenant_upload regardless. The provenance 63 half of this step needs no document at all. 64 The column is file_name, not filename. 65 66 STEP 2 RUNS. cmd/opportunity-extract -dsn <dsn> -storage-root <root>. 67 DETERMINISTIC only, no model. 68 Proves: headings, numbered clauses, tables, dates, deadlines, dollar 69 values, labor categories, quantities, clearance terms, certifications, 70 locations, travel percentages, period of performance, deliverables, and 71 evaluation factors land in opportunity_document_chunks WITH provenance: 72 page, section label, content hash, extraction method, confidence. 73 ASSERT: every chunk carries its provenance. A chunk that cannot say 74 where it came from cannot support a cited scope item later. 75 76 STEP 3 cmd/opportunity-scope-normalize, the model pass, LOCAL plane only. 77 RUNS TODAY, on notice METADATA. It composes nine header fields, about 78 250 bytes. It will consume a PWS only once steps 1 and 2 exist, and 79 until then the scope items restate the notice header. 80 ASSERT FIRST, before running: the payload composer must refuse. The 81 document is provenance tenant_upload, and AllowEgress refuses any 82 payload whose element set contains it. THIS IS THE TEST THAT MATTERS 83 on a real document: the external lane must be structurally unreachable 84 for a customer's own package, not merely unused. 85 Then run it against the LOCAL model and confirm cited scope items. 86 Invocation, proven in the rehearsal: 87 go run ./cmd/opportunity-scope-normalize -dsn <migrator> \ 88 -megamind http://100.94.8.94:8091 -token <gateway token> \ 89 -limit 1 -dry-run 90 The staging gateway token is in the staging secrets file, NOT the 91 production api.env. The production token returns 401 here. 92 ASSERT: ck_scope_items_cited refuses any uncited machine produced item. 93 ASSERT: a fabricated citation, a quote not present in the source text, 94 is rejected by ValidateScopeCandidates. 95 96 STEP 4 Scope review queue, screen 4, as a recruiter and as a manager. 97 Accept, edit and accept, reject, split, merge, add manually. 98 ASSERT: every item shows its document name, page or section, extraction 99 method, and confidence. A reviewer who cannot see the provenance is 100 approving a claim rather than checking one. 101 102 STEP 5 Requirement drafts, screen 5, then PROMOTION. 103 ASSERT: promotion records the NAMED HUMAN. TWO constraints do this and 104 they fire in a FIXED ORDER, so testing only one proves only one: 105 ck_drafts_approved_has_requirement fires FIRST, an approved draft 106 must carry approved_requirement_id 107 ck_drafts_decided_has_reviewer fires only once the first is satisfied 108 Assert BOTH, and follow them with a plain draft insert as the positive 109 control, because a table that refused everything would look identical. 110 review_status is draft, in_review, approved, rejected. There is no 111 "pending". The label column is labor_category, there is no "title". 112 ASSERT: the promoted requirement links only skills the EXISTING ontology 113 knows. A solicitation names skills the ontology lacks; those stay 114 unlinked, because writing the global ontology is operator curation and 115 never a side effect of approving one requirement. 116 117 STEP 6 AMENDMENT. Ingest the amendment. 118 ASSERT: a NEW immutable opportunity_versions row, its predecessor 119 retired in the SAME transaction, the ingest manifest cited. 120 ASSERT: the diff flags deadlines, labor categories, quantities, security 121 requirements, and evaluation criteria. 122 ASSERT: affected APPROVED requirements are FLAGGED for a named human and 123 NOT rewritten. This is acceptance item 11 and the whole safety promise. 124 The synthetic proof already passed: an approved requirement survived 20 125 ingest rounds byte for byte. The real package proves it on real text. 126 127 STEP 7 The two DEFERRED PHASE 1 ITEMS, BOTH NOW BUILT as of 28 July. The 128 upload screen handler exists and cmd/sam-attachment-sync pulls the 129 public attachment package. What the trial adds is the first exercise of 130 both against documents nobody here authored. 131 intake screen 3, uploads, with drag and drop, progress, extraction 132 status, retryable errors, and duplicate detection by sha256 133 cmd/sam-attachment-sync, downloading queued public attachments 134 CORRECTED 28 July 2026: the earlier line here said both were deferred 135 on documents existing and never on engineering. The upload screen has 136 no handler behind it and there is no extraction binary at all, so that 137 claim was wrong for the upload half and is withdrawn. The attachment 138 sync genuinely does wait on public attachments existing. 139 140## THE GATES THIS CLOSES 141 142 GATE 1 remainder: uploads validated, hashed, versioned, traceable. NOT closable 143 by the package alone, see steps 1 and 2. 144 GATE 2 remainder: every extracted scope item carries a source citation, on a 145 REAL document rather than a fixture. The synthetic halves are already proven 146 and filed under docs/evidence/phase2/. The REAL document half waits on the 147 same engineering, because nothing today puts a document in front of the 148 extractor. 149 150## WHAT IS ALREADY PROVEN AND DOES NOT NEED REDOING 151 152 Uncited model output rejected, by test AND by a live insert refusal. 153 Eight racing promotions elect exactly one requirement, and thirty two also. 154 Ingest during promotion corrupts nothing; approved requirements survive it. 155 The external boundary refuses candidate rows and tenant documents by 156 provenance bound at origin, with the binding sites enumerated by test. 157 Schema constraints proven against a live database by six refusal tests. 158 159## THE ONE JUDGEMENT CALL TO EXPECT 160 161A real PWS will name skills the ontology does not carry. That is NORMAL and the 162correct behaviour is to leave them unlinked and surface them, NOT to write the 163global ontology. If the trial produces a long list of unlinked skills, that is a 164curation backlog for an operator, not a defect. Recording this in advance so it 165is not mistaken for a failure on the day. 166