Sooner Underwriting — Implementation Notes

Running log of design decisions, deviations from spec, tradeoffs, and open questions across the underwriting work.
Owners: T1 = canonical (sooner-underwriting-sandbox), T3 = forms (sooner-gtm-forms, branch t3/sooner-application-forms).
Started 2026-05-19 by Opus 4.7 (master orchestration). T2 and T4 deferred.

1. Current state snapshot (2026-05-19)

T1 — canonical sandbox (APP-1863)

T3 — forms (GTM-59)

2. Spec divergences and decisions taken

TagItemSource spec positionDecision / deviation takenReason
decision Master orchestration moves back to Opus sooner-orchestration-handoff.md says "coordinator rewrites are Codex-maintained" while Opus blocked. Opus 4.7 is now the planning seat. Codex stays as the implementation engine per codex-routing.md (80/20 Codex/Opus on code-touching turns). User explicitly invoked a master Claude session to drive synthesis and sub-sessions.
deviation Form 2.5 (optional co-applicant) added to the funnel gabriel-spec.md defines a 3-form funnel (Form 1 / Form 2 / Form 3) with no Form 2.5. Treat Form 2.5 as an optional branch off Form 2: if Q "Will a co-applicant be on the mortgage?" = yes, surface a parallel mini-form capturing co-applicant employment, income, debts. Otherwise skip. Renders inline on desktop, separate step on mobile. Co-applicant data is currently buried inside app/sooner-app.html dashboard; needs to move upstream so SCS can run with both applicants' data before document upload.
deviation Pricing-tier ladder (10% / 12.5% / 15%) added to T1 canonical Engine packages/config/json/pricing-card.json has only a flat 16.5% monthly collection rate. criteria.v0.json has no fee structure at all. The 10/12/15% ladder is not modeled anywhere in code. Add a new contract section criteria.fees with shape: 
{
  "version": "0.1.1",
  "tiers": [
    { "id": "all_three", "feePct": 10,
      "services": ["closing_fee_financing","home_discovery","mortgage_brokerage"] },
    { "id": "two_with_cff", "feePct": 12.5,
      "requires": ["closing_fee_financing"], "additionalAnyOf":
        ["home_discovery","mortgage_brokerage"] },
    { "id": "cff_only", "feePct": 15,
      "services": ["closing_fee_financing"] }
  ]
}
T3 forms read this contract and dynamically display the applicable rate based on service selections. 		User stated this is the canonical fee structure. Embedding once in T1, consumed by T3, prevents drift.
decision Forms render consequences messaging live Not in spec. Each answer that changes pricing or doc requirements renders an inline advisory: e.g. "Selecting Mortgage Pre-Approval already in hand means we cannot help you switch banks." / "Adding Home Discovery drops your service fee from 12.5% to 10%." Implementation: declarative rules co-located with question definitions; messages are content slots, not modals. User asked for forms to "tell the customer about the consequences of their actions." Doing this declaratively keeps it maintainable.
decision HTML helper pages live in sooner-coordination/ (this folder) No spec position. Both forms-inventory.html and matrix-browser.html live here. They are view layers over canonical data — they don't own data, they render data shipped from sooner-underwriting-sandbox (employer + location taxonomies) and sooner-gtm-forms (question definitions). Keeps inventory artifacts repo-agnostic. Avoids the trap of inventory living inside the code repo and getting stale at merge time.
tradeoff Document-import opportunities highlighted only, not implemented User scope. Identify each form field that could be auto-filled from an uploaded document (Emirates ID, salary cert, bank statement, AECB report) and tag it in forms-inventory.html. Do not wire OCR or extraction yet. Tag class: importable-from. OCR pipeline is its own engineering effort (Bedrock vs Azure vs Extend AI bake-off per uae-ocr-strategy.md memory). Premature to mix.
decision T3 question reconciliation against T1 A0 happens via a generated mapping doc t3-field-audit.md recommends docs/criteria-field-map.md after A0 accepted. Maintain the mapping as a checked-in JSON file (sooner-gtm-forms/underwriting-funnel/field-map.json) keyed by canonical field name → list of form locations using it. Generate the human-readable view from JSON. JSON is diffable, lets us write tests that fail when a form drops a required field.
tradeoff T1 sandbox stays not-on-GitHub for now T1 STATUS.md flags this as an open blocker. Don't block on GitHub publication this turn. The contracts are vendored into T3 already; downstream consumers don't need a remote until A1 sign-off. Open ticket exists. Forces no work; can be solved out-of-band whenever GitHub App access is confirmed.

3. Gaps identified

T1 gaps (canonical)

T3 gaps (forms)

4. Open questions for Gabriel

#QuestionDefault I'm assuming
Q1 Where should forms-inventory.html and matrix-browser.html ultimately live? Inside sooner-underwriting-sandbox as part of the canonical surface, or stay in sooner-coordination/ as orchestration artifacts? Stay in sooner-coordination/ until A1 sign-off, then move matrix-browser.html into sandbox (lender-facing) and forms-inventory.html into sooner-gtm-forms/docs/.
Q2 For pricing tiers — is "Closing Fee Financing" always required (i.e. the customer cannot choose Home Discovery + Mortgage Brokerage without CFF)? Yes — CFF is the core product. Other two are upsells. The 12.5% tier assumes CFF + one upsell. The 10% tier assumes CFF + both upsells.
Q3 Does Form 2.5 co-applicant data flow into the same SCS computation, or run as a parallel score that Reliable's underwriter weighs? Same SCS — co-applicant income increases household income, co-applicant debts increase DBR. SCS is a joint score.
Q4 Master Claude session — should the sub-sessions (T1, T3) commit back to a single shared dir (this sooner-coordination/) or should each session own its repo and the master just reads? Master writes to sooner-coordination/. Sub-sessions write to their own repos but emit handoff stubs into sooner-coordination/handoffs/ for the master to consume.
Q5 Are T2 and T4 truly deferred for the next 2 weeks, or just lower priority? (Affects whether their contracts can drift independently.) Deferred. T2 stays in In Review, T4 stays in Preping. No new commits on either track from the master.

5. Next concrete deliverables (queued)

  1. Build forms-inventory.html — table of Form 1 / Form 2 / Form 2.5 / Form 3 with question lists, lengths, info captured, gaps, doc-importable tags. Dispatch to codebase-explorer subagent to map question definitions, then this master writes the HTML.
  2. Build matrix-browser.html — searchable list of named employers + industry tier matrix + master-community / sub-community / developer tier. Reads from sooner-underwriting-sandbox/contracts/source-snapshots/employer-classification.json and community-classification.json.
  3. Add fees contract to T1 — contracts/criteria.v0.json bump to 0.1.1; add fees section. Dispatch to Codex per routing rules.
  4. Wire pricing-tier display + consequences messaging into T3 forms — declarative rule format, single source-of-truth for advisory copy. Dispatch to Codex.
  5. Generate field-map.json — canonical → form-location mapping for T3 reconciliation against A0.
  6. Confirm Reliable Mortgages doc requirements — Mo/Vlad action; tracked separately.

6. Update log

This doc is the running source of truth for divergences between SPEC and what we build. Every sub-session (T1, T3) appends an entry to §6 when it lands a decision or hits a deviation. Master session reconciles weekly.