session topology

Sooner Underwriting — Claude Session Topology

Last updated: 2026-05-19, Opus 4.7 (master) Replaces: the Codex-led coordinator described in sooner-orchestration-handoff.md (kept for provenance; that file is now read-only history).

Purpose

One master Claude session drives synthesis and gap-finding. Sub-sessions execute focused tracks. The split exists so context stays clean (each repo’s noise stays in its own session) while a single high-context surface watches for drift across tracks.

Topology

                         ┌──────────────────────────────────────────────┐
                         │  MASTER (this session)                       │
                         │  Opus 4.7, working dir = sooner-coordination │
                         │                                              │
                         │  Owns:                                       │
                         │  - implementation-notes.html (running log)   │
                         │  - forms-inventory.html (T3 helper)          │
                         │  - matrix-browser.html (T1 helper)           │
                         │  - session-topology.md (this file)           │
                         │  - cross-track gap detection                 │
                         │  - dispatches to Codex per codex-routing.md  │
                         └──────────────────────────────────────────────┘
                                       │              │
                ┌──────────────────────┘              └──────────────────────┐
                ▼                                                            ▼
   ┌──────────────────────────────┐                          ┌──────────────────────────────┐
   │  SUB: T1 — Canonical          │                          │  SUB: T3 — Forms              │
   │  Opus 4.7                     │                          │  Opus 4.7                     │
   │  cwd = sooner-underwriting-   │                          │  cwd = sooner-gtm-forms       │
   │        sandbox                │                          │  branch = t3/sooner-          │
   │                               │                          │           application-forms   │
   │  Owns:                        │                          │  Owns:                        │
   │  - criteria contracts         │                          │  - Form 1, 2, 2.5, 3 HTML    │
   │  - employer/location matrices │                          │  - field-map.json             │
   │  - /criteria, /profiles,      │                          │  - consequences-rules.json    │
   │    /playground UI             │                          │  - pricing display logic      │
   │  - Vercel + Railway deploy    │                          │  - Supabase/Apps Script glue │
   │                               │                          │                               │
   │  Linear: APP-1863             │                          │  Linear: GTM-59               │
   └──────────────────────────────┘                          └──────────────────────────────┘

   (T2 — dashboard, APP-1865) DEFERRED
   (T4 — retargeting, APP-1866/GTM-60) DEFERRED

Roles

Master (this session)

Reads Linear, reads all three repos read-only by default.
Maintains implementation-notes.html as the running log.
Builds and updates forms-inventory.html and matrix-browser.html (these are views over sub-session data, owned by master).
Detects cross-track drift (e.g. T3 form asks for a field T1 doesn’t yet emit in profile-input contract).
Dispatches implementation to Codex per ~/.claude/rules/codex-routing.md.
Owns the Linear status sync for the master ticket and cross-track items.

Sub-session T1

Single focus: ship canonical sandbox at v0.1.1 with the new fees contract section.
Lives in its own Claude Code session with cwd=sooner-underwriting-sandbox.
Writes to its own repo only. Emits handoff stubs to sooner-coordination/handoffs/T1-<date>.md when it lands a decision or hits a blocker.
Linear ticket: APP-1863. Sub-tickets attach as children.

Sub-session T3

Single focus: get Form 1 / 2 / 2.5 / 3 question-complete and pricing-aware, ready to hand to Moaziz for UX polish.
Lives in its own Claude Code session with cwd=sooner-gtm-forms, branch t3/sooner-application-forms.
Writes to its own repo only. Emits handoff stubs to sooner-coordination/handoffs/T3-<date>.md.
Linear ticket: GTM-59. Sub-tickets attach as children.

Standing instructions (passed to every sub-session)

Every sub-session opens with this standing prompt header:

You are a sub-session under the master Sooner Underwriting orchestration.
Read first: ~/Desktop/Projects/sooner-coordination/implementation-notes.html
            ~/Desktop/Projects/sooner-coordination/session-topology.md
Your scope is bounded — only touch [REPO]. Do not touch other Sooner repos.

Decision discipline:
- If you make a design decision that diverges from spec, append an entry
  to implementation-notes.html §6 (update log) with the decision tag and
  date. Master reconciles weekly.
- If you hit a blocker on a contract owned by another track, emit a stub at
  sooner-coordination/handoffs/<your-track>-<YYYYMMDD>.md describing the
  blocker and which track owns the unblock.
- All implementation code goes through Codex per codex-routing.md.
  Your role is plan + review, not type.

Linear discipline:
- Move your ticket to "In Review" on PR open, "Done" on PR merge
  (per linear-status-sync.md).
- Assign sub-tickets to me (gabriel@getrematched.com) per linear-ticket-
  assignment.md.

Communication back to master:
- When you ship a slice, summarize what changed in the handoff stub.
- Do not duplicate work the master is doing (HTML helpers, cross-track
  reconciliation).

Adversarial review before PR:
- Run rematch-engineering:re:review --adversarial on every PR before
  marking ready, per pre-pr-review-discipline.md.

Repo-specific context lives in that repo's CLAUDE.md / AGENTS.md.

Handoff protocol

When a sub-session needs the master to react (decision needed, contract drift, blocker on another track), it writes a stub:

sooner-coordination/handoffs/T<n>-<YYYYMMDD>-<slug>.md

---
from: T1 | T3 | T2 | T4
to: master
type: decision-needed | blocker | contract-change | drift-detected
priority: P0 | P1 | P2
---

## Context
<what's happening>

## Decision needed / blocker
<specific ask>

## Proposed default
<what I'll do if you don't respond>

## Files touched
<list>

Master polls sooner-coordination/handoffs/ at session start. Resolved handoffs move to handoffs/resolved/<YYYYMMDD>/.

Cadence

Master session: runs when Gabriel wants synthesis or to launch a sub-session. Long-lived; preserved across compacts via implementation-notes.html + handoff stubs (handoff-parity rule).
T1 sub-session: runs when contract or matrix work happens. Short-lived per slice (one cohesive PR per session per pr-cadence.md).
T3 sub-session: runs when form work happens. Same per-slice cadence.

What goes through Codex

Per codex-routing.md: 80/20 Codex/Opus on code-touching turns. Opus plans, Codex implements. Bounded exceptions for trivial edits and review-feedback fixes. The master session does NOT directly edit code in sooner-underwriting-sandbox or sooner-gtm-forms — that goes through Codex via the spawning sub-session.

The master DOES directly edit sooner-coordination/*.html because that’s harness/orchestration tooling, not production code.

When to retire a sub-session

A sub-session retires when: 1. Its current Linear ticket transitions to Done. 2. Its repo has clean working tree and committed handoff stub. 3. Master has read the handoff stub and updated implementation-notes.html.

When T2 / T4 reactivate

They get their own sub-sessions, mirroring T1 / T3, when Gabriel signals. Same standing instructions. They will need to read implementation-notes.html first to pick up cross-track context.