Janady13/missionmatch / docs/superpowers/specs/2026-07-27-opportunity-to-outcome-execution-design.md

1# Opportunity to Outcome, missionMATCH Execution Design 2 3Date: 27 July 2026 4Branch: feature/opportunity-to-outcome (created off 462eb81) 5Product spec and phase plan: CLAUDE_CODE_BUILD_DIRECTIVE.md (the single source of truth) 6 7This is the EXECUTION design. It does not redesign the product. The directive already 8fixes the architecture, data model, API routes, binaries, phases, and gates. This 9document records how the build runs safely against the live federation, and the 10decisions Joseph approved on 27 July 2026. 11 12## Approved decisions (27 July 2026) 13 141. Verification target: there is no separate staging. Joseph's decision on 27 July 2026 15 supersedes the staging amendment. The build extends the existing application directly 16 and verifies against the live database per directive Section 0 item 7, with a connected 17 database name assertion and a pg_dump snapshot before every schema change, additive and 18 transactional migrations, and down migrations that refuse to destroy application rows. 192. Cadence: autonomous through the phases. Surface only at a failing gate or a human 20 blocker. 213. OpenAI scope: a two lane AI layer. The OpenAI lane sees PUBLIC data only. Private 22 tenant, candidate, resume, scoring, slate, and EEO data stays on the local plane, 23 always. 244. Deploy to BOTH API nodes on every release, closing the single node gap in 25 scripts/deploy.sh. 26 27## Federation and source of truth 28 29Canonical source of truth is this Mac repo, /Users/josephanady/missionmatch, HEAD 30462eb81, which matches the live deployed mm-api binary and the architecture document. 31The Mac has the Go 1.26.4 toolchain and direct tailnet reach to both databases and both 32API nodes, so it builds, migrates, verifies, and deploys. 33 34Live topology in play: 35 36 Bubbles 100.90.97.104 nginx ingress, mm-api node one, /home/user/missionmatch 37 megamind-agi 100.77.114.40 mm-api node two, control plane Postgres :5433 38 M4 mini 100.94.8.94 tenant Postgres :5432, megamind-gateway :8090 (inference) 39 40Tenancy is per_tenant in production. Tenants seen today: acme business plus 41acme_compliance. Identity and tenant_directory live in the control plane. New tenant 42tables live inside each tenant database. 43 44## Pipeline: build, migrate, deploy, verify 45 46Baseline is scripts/deploy.sh, which is trusted for its staged sha256 swap that avoids 47ETXTBSY, its stop before swap, its preservation of the injected SEO lines in index.html, 48and its five second boot wait. Two gaps are closed by this build. 49 50Gap one: deploy.sh ships only to Bubbles. Both nodes must run the same binary or the two 51node failover drifts. Every release also ships to the megamind-agi replica. 52 53Gap two: deploy.sh runs migrations as single DSN goose. Production is per_tenant, so new 54tenant tables fan out through cmd/migrate-all-tenants across every tenant database, and 55control plane changes apply to the control plane. Never the single DSN path for tenant 56tables. 57 58Safety rails, building into the existing application (no separate staging): 59 601. Assert the connected database is the intended production database before any write, so a 61 wrong DSN cannot hit the wrong database on the shared M4 server. 622. A pg_dump snapshot of each target database immediately before any migration batch, so 63 every schema change is reversible. 643. Every migration additive and transactional. Down migrations refuse with a count rather 65 than destroy application authored rows, per directive section three. 664. The tenant fields survive a source refresh byte for byte test, from directive section 67 four item twelve, runs and passes before any sam-sync write path is trusted. 685. New binaries deploy to both API nodes, and every item is verified end to end through the 69 live authenticated API and the rendered screen. 70 71Build flags stay FIPS and Linux: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 72GOFIPS140=v1.0.0 go build -trimpath. New job binaries cross compile the same way, ship to 73/home/user/missionmatch on both nodes, and run as idempotent, bounded, observable, 74audited systemd timers safe to rerun. 75 76Verification method, unchanged: reproduce against the live database first, implement, 77verify against the same database, verify end to end through the live authenticated API, 78then look at the rendered screen. Concurrency is proven by racing it. 79 80## Ledger and frozen set 81 82docs/BUILD_STATE.md is the append only ledger. One line per verified gate item: phase, 83item, verification evidence (the command run, the rows observed, the screen checked), 84commit hash, and date. Only verified items enter. Aspirations never enter. 85 86Commit convention: "phaseN itemM: short description", one logical change per commit. 87 88Frozen and untouchable: internal/modules/matching/engine, db/migrations_eeo, every 89existing migration file, generated sqlc output (regenerate, never hand edit), and the 90append only audit semantics. Final acceptance check twenty three, an empty diff of the 91candidate scoring engine against the starting commit, is a hard invariant guarded every 92phase. 93 94## Two lane AI 95 96OpenAI lane, public data only, off until the key is rotated: 97 98- Compliance matrix and scope extraction from PUBLIC solicitation text. 99- Opportunity triage summaries and go or no go analysis over PUBLIC opportunity and 100 market data. 101- Behind the internal/platform/scrub egress gate, verifier gated exactly as local models 102 are, recorded in the model registry and AEDT inventory as outside the FIPS boundary, 103 restricted to non regulated tasks. Every external call audits backend name, payload 104 class, byte count, and content hash, never content. 105 106Local lane, never leaves the machine: 107 108- The in app assistant over the tenant candidates, slates, scores, and recruiting 109 pipeline, extended through the existing RouteRAG and RouteGraph orchestrator on 110 megamind-gateway to be materially smarter. No external API, ever. 111 112The scrub gate fails closed to the local plane. Forbidden external, enforced by the gate 113and by tests: candidate rows, resume text, names, emails, phone numbers, tenant 114identifiers, anything from the eeo schema, RouteRAG and RouteGraph over tenant data, 115scoring inputs, scoring outputs, and slate contents. 116 117## Knowledge feeding 118 119Knowledge enters only as cited, provenance tracked curated cards through curation.curate, 120plus licensed ontologies, each traceable to an ingest_manifest row. No arbitrary document 121dumping into a model. When the build reaches Phases two and four, Joseph designates which 122documents are the canonical knowledge (candidates include the Owner's Manual, the complete 123manual, and the SAM solicitation packages), and they are ingested with provenance and zero 124fabrication. 125 126## Phase order and human blockers 127 128Execute Phases zero through six autonomously, each gate verified and recorded before the 129next begins. Pause and surface on these human steps only: 130 131- Phase 0 item 1: revoke the OpenAI key exposed in chat on 27 July 2026. Immediate. 132- Phase 0 item 2: create a fresh project scoped key under Mission Workforce Technologies 133 with a monthly cap and budget alerts, placed in internal/platform/secrets as 134 openai_api_key, root owned 0600 on M4, nowhere else. 135- Phase 0 item 3: begin the SAM.gov system account application. Weeks of lead time, needed 136 in Phase 4. 137- Phase 6 item 1: enable MFA and set MM_ENV to production. The go live decision. 138 139Everything that does not depend on these proceeds without waiting. 140 141## Phase 0 concrete work, this session, no human dependency 142 1431. Build branch feature/opportunity-to-outcome. Done. 1442. docs/BUILD_STATE.md created with the ledger format. 1453. Move INTELLIGENCE_EXPANSION_SPEC.md into docs/archive so exactly one work order exists. 1464. Implement the scrub gate egress payload classes and the external call audit rows, with 147 the OpenAI backend enabled flag still false. 1485. Add the OpenAI backend to megamind-gateway with the boot guard: enabled plus no secret 149 refuses to boot. 150 151Gate 0: the gateway with openai enabled and no secret refuses to boot, proven against a 152live gateway instance. Scrub tests pass. BUILD_STATE exists. The archive move is 153committed. 154