MIS ARCHITECT: MASTER CONTEXT & DEVELOPER RULES

Phase 2 Blueprint — drafted Session 8 (2026-04-15)

🪦 SUPERSEDED 2026-04-28 by docs/MIS_FSE_ARCHITECTURE.md (FSE = FINAL_STATE_ENGINE arch). FSE doc explicitly supersedes Phase 2 — see FSE doc §11. Phase 2 prescribed a Yahoo Finance + JS-only Microservices rewrite that diverged into the Architect V11 sandbox sheet — that diverged sheet is what creates the surface conflicts FSE is built to solve. Read FSE doc first for current MIS architecture. This file kept as historical context for the Microservices intent.

1. System Philosophy & Architecture

MIS Architect is a quantitative, market-aware technical screening engine designed for 3:00 PM Power Hour execution. It operates on a Microservices Architecture.

• No Google Finance Cell Formulas: Legacy system used =GOOGLEFINANCE causing 20-min hangs and data corruption. Strictly forbidden going forward.
• The Monitor vs. The Hard Drive: Google Sheet is just a "monitor" (UI). Engine lives in Google Apps Script memory.
• Auto-Regeneration: System requires only a Tickers tab. Code draws dashboard, playbooks, diagnostic tabs on the fly.

2. The Math Engine (Phase 1.5 — COMPLETED)

All logic calculated in-memory via JavaScript arrays using Yahoo Finance REST API.

• ATR: 14-day True Range average (high-low-prevclose method)
• Stop: Current - (ATR × 1.3)
• Dollar Risk: Portfolio × 0.01 ($250 on $25K)
• Shares: Math.floor(Dollar_Risk / stopDistance)
• Capital Cap: Max 20% of portfolio per position
• SACS: 0-100 weighted score: base 50 + (zScore14 × 15), adjusted for accumulation/distribution, compression, volume, RS vs SPY, headline penalty
• Headline Overlay: RSS news — hard block for fraud/bankruptcy, -18 to -30 SACS for negative keywords, downgrade to WATCH on bearish catalyst
• MacroBias: VIX regime + breadth ratio — DEFENSIVE if VIX EXTREME or breadth.down > breadth.up × 1.5
• Max outputs: 5 LEAN IN, 5 STARTER — ranked by SACS then relStrength30 as tiebreaker

Reference code: V10.5 Perfect Presentation engine (ingested Session 8)

3. The Reality Layer (Phase 2 — CURRENT OBJECTIVE)

Transition from paper money to broker-aware logic. Implement legacy mechanisms without cell formulas.

3a. Trade Planner (Open Positions DB)

Tab: Trade_Planner
Columns: Date | Account (Schwab/Fidelity) | Ticker | Side | Entry | Stop | Target | Shares | Status
- Account values: Invest n Save (Z29720600) | Joint Brok (Z29835692)
- Youth account Z27934073 excluded at ingestion
- Script builds tab if missing; never overwrites existing rows

3b. Holdings PnL Tracker

Tab: Holdings
- Reads Trade_Planner for open positions
- Fetches live price via existing fetchSingleTickerData() API call (no GOOGLEFINANCE)
- Writes static arrays: Ticker | Account | Shares | Entry | Live Price | Unrealized $ | Unrealized %
- Refreshes on each Power Hour run

3c. Position Overlap Block (TWO GATES)

Gate 1: If ticker already in Trade_Planner at max allocation → Hard Block new setup for that ticker
Gate 2: Total open risk across ALL positions must not exceed 6% of portfolio (6 × $250 = $1,500 total book risk)
- Helper: isTickerHeld_(ticker, tradePlanner) → returns boolean
- Called in evaluateTicker() before SACS calculation

3d. Bracket Order Playbook

Email output format per trade:

BUY LMT  [TICKER]  [SHARES] shares @ $[ENTRY]
STOP     $[STOP]   (1.3 ATR = $[STOP_DISTANCE])
TARGET   $[TARGET] (2.5R = $[TARGET_GAIN])
RISK     $[DOLLAR_RISK] ([RISK_PCT]% of portfolio)

3e. Earnings Quarter-Roll (Finnhub)

• API key stored in PropertiesService.getScriptProperties() as FINNHUB_API_KEY
• Fetch earnings date from Finnhub; if date is in the past, roll forward 91 days (projectQuarterForward_())
• If Finnhub fails → fallback to existing EARNINGS_MASTER tab data
• Flag in email: ⚠️ EARNINGS [DATE] — reduce size if within 7 days

4. New Module: portfolio-sync.js

Standalone Apps Script file to add alongside existing engine. Functions:

buildTradePlannerTab(ss)        // Auto-creates clean Trade_Planner if missing
syncHoldingsPnL(ss)             // Reads Trade_Planner, fetches live prices, writes Holdings
isTickerHeld_(ticker, ss)       // Returns true if ticker in Trade_Planner (open status)
getTotalBookRisk_(ss)           // Returns sum of all open position dollar risks
buildEarningsOverlay(tickers)   // Fetches Finnhub dates, rolls past dates forward 91 days

Integration point in main engine — in evaluateTicker(), after lethalBlocks init:

if (isTickerHeld_(ticker, ss)) lethalBlocks.push('ALREADY_HELD');
if (getTotalBookRisk_(ss) >= CONFIG.portfolioSize * 0.06) lethalBlocks.push('BOOK_RISK_MAX');

5. Strict AI Developer Directives

1. Never break Phase 1.5: Do not alter core SACS math, risk sizing, or HTML email output
2. Zero hardcoding of API keys: Use PropertiesService.getScriptProperties() for Finnhub, Schwab tokens
3. No 2D array mismatches: All sheet write arrays must be perfectly rectangular
4. No PDF exports until Playbook_V2 tab logic is rebuilt (currently shows all tickers as LEAN IN regardless of signal)
5. Account masking in all outputs: Display as Invest n Save (...0600) never raw account numbers

6. Known Bugs Fixed This Session (Session 8)

7. Session Handoff Prompt (for next Claude session)

Role: Lead Systems Architect, Senior Google Apps Script Developer.
Project: MIS Architect Phase 2 — The Reality Layer.
Files to attach:
1. MIS_PHASE2_BLUEPRINT.md — architectural rules (read first)
2. emailDailySnapshot.js — current working Phase 1.5 engine (do not break core math)
3. Code.js — legacy tab builder (extract Trade_Planner, Holdings, Finnhub logic only)

Task: Write portfolio-sync.js — a modular Apps Script file that:
1. Auto-builds Trade_Planner tab for manual entry of open trades (Schwab/Fidelity)
2. Auto-builds Holdings tab reading Trade_Planner, uses fetchSingleTickerData() for live prices, writes static PnL arrays (no GOOGLEFINANCE)
3. Provides isTickerHeld_() and getTotalBookRisk_() helpers for overlap/book-risk gating
4. Provides buildEarningsOverlay() with Finnhub + 91-day quarter-roll fallback

Output: portfolio-sync.js code + exact insertion points in main engine.