Instance 1 — one brain for the deal pipeline

The deal-FSM refactor + a 5-layer spec that keeps code and intent in lockstep

Master summary — the gist in 30 seconds

TL;DRWe gave the sales pipeline a single decision-maker for where every deal sits — and then wrote it down at five altitudes so it can never quietly drift.

Input: deal logic scattered across ~28 places (which caused a card to jump to 'Negative' 1 second after a rep logged a call, and cards routing to different columns depending on which copy of the code ran). Output: one authority (deal_fsm.py) that every path asks, plus a 5-layer written spec with an automatic guard that blocks the code from drifting from the spec. Test suite grew 1206 → 1415, all green; the two named bug-fixes still hold; nothing that sends to a lead was touched.

Why this mattersWhen many places each decide the same thing their own way, they eventually disagree — and disagreements in a sales pipeline look like a customer's card silently landing in the wrong column, or a human's decision being overwritten by a robot. Funnelling every decision through one authority makes 'the wrong thing' structurally impossible, not just discouraged.

flowchart LR
  Scatter["~28 scattered<br/>decision points"] --> FSM["deal_fsm.py<br/>ONE authority"]
  FSM --> Spec["5-layer spec<br/>+ drift-gate"]
  Spec --> Trust["code & intent<br/>stay in lockstep"]

1 · One brain instead of many hands

TL;DRThree tangled 'seams' — column, disposition, stage — now all run through a single module.

Input: three separate messes — how a deal's board COLUMN is computed (T1, which existed in two copies, one stale), how a NEGATIVE reply is recorded (T2, ad-hoc in 6 places), and how a deal's STAGE is changed (T3, with a bypass that skipped the audit trail). Output: deal_fsm.py owns all three — derive_column (T1), set/dispose/clear_negative (T2), transition (T3) — and the old callers now just ask it.

Why it mattersA single authority is the difference between a rule you HOPE everyone follows and a rule that is enforced in one place. The stale second copy of the column logic was a live latent bug — once there's only one copy, a whole class of 'why is this card in the wrong lane?' mysteries can't happen again.

flowchart TD
  subgraph Before
    A1["board_view.deal_col"] -.->|copy drift| A2["dash._deal_col<br/>(STALE)"]
    A3["neg_reply set in<br/>6 places"]
    A4["stage set 2 ways"]
  end
  subgraph After
    F["deal_fsm.py"]
    F --> C["derive_column"]
    F --> N["set / dispose / clear_negative"]
    F --> S["transition"]
  end
  Before ==> After

2 · The human always wins (the B1 guard, now structural)

TL;DRA robot can no longer overwrite a person's decision — the rule is built into the authority, not left to each caller to remember.

Input: a rep logs a call on a deal, then an automated email-classifier sees an inbound reply ~1 second later and wants to mark it 'Negative'. Output: the FSM refuses the automatic mark when a human has already acted (a logged call or a set follow-up) — but a human can still mark it negative anytime. Before, this rule lived as a fragile check inside one function; now it's the authority's own law.

Why it matters'Structural' means the wrong move isn't just discouraged, it's impossible — the illegal transition is rejected at the door. This is the exact bug (B1) that used to make a rep's careful call disposition vanish under an eager auto-classifier. Making it a law of the machine, not a habit of the callers, is why it can't quietly regress.

flowchart TD
  Call["Rep logs a call"] --> Human{"Human already<br/>decided?"}
  Email["Auto classifier:<br/>'looks negative'"] --> Ask["set_negative(auto)"]
  Ask --> Human
  Human -->|yes| Reject["REJECTED —<br/>card stays put"]
  Human -->|no| Allow["marked Negative"]
  HumanMark["Human clicks 'negative'"] --> Always["ALWAYS allowed"]

3 · Written down five ways, guarded automatically

TL;DRThe same machine is described at five altitudes — plain vocabulary, state map, human answer-key, replayable log, executable scenarios — and a pre-commit gate blocks the code from drifting from its spec.

Input: a codebase where the 'rules' lived only in the code and people's heads. Output: five linked layers (00-vocabulary → L0 FSM → L1 EBO answer-key → L2 event-log → L3 Gherkin → L4 SPEC) all speaking one frozen vocabulary, plus scripts/spec_drift_gate.py — a hook that blocks a commit if the code's public contract diverges from the written SPEC. We proved it fires: aligned = pass, tampered = blocked, reverted = pass.

Why it mattersDocs rot because nothing forces them to stay true. The drift-gate turns the top spec layer into a tripwire: change the code's shape without updating the spec and the commit is refused. So the '5 layers' aren't decoration — one of them actively defends the honesty of the rest, which is what makes the whole model trustworthy months from now.

flowchart LR
  V["Vocabulary<br/>(frozen)"] --> L0["L0 FSM<br/>state map"]
  L0 --> L1["L1 EBO<br/>answer-key"]
  L1 --> L3["L3 Gherkin<br/>scenarios"]
  L0 --> L2["L2 event-log<br/>replayable"]
  L0 --> L4["L4 SPEC<br/>+ drift-gate"]
  L4 -->|blocks drift| Code["deal_fsm.py"]
  Code -->|checked against| L4

5-layer spec index →Unifying diagram →Before-state coupling map →Full I1 report (with pixel smoke) →