candidate guards (peak-cycle, extended, informed money leaving) + analyst committee screen on prospective additions; switches/target need a clean committee verdict

README.md

@@ -60,6 +60,11 @@ entry price, quantity optional), and get:
   holdings, effective-N, beta, worst crash replay, yield, DCF gap — and only fit-eligible
   names reach the CIO and the switch engine. Each pick states the problem it fixes with the
   number ("moves opposite your holdings (correlation −0.40) · cuts the 2022 replay −53%→−49%").
+  Deterministic guards a quant rank never applies (peak-cycle earnings in a cyclical business,
+  an extended price, informed money leaving) surface as cautions and cost fit; then the same
+  five analyst lenses **screen every shortlisted candidate as a prospective addition** — a
+  name the committee would not add (below 52/100) is never recommended or used as a switch
+  destination.
 - **Recommendation completeness** — every Trim/Sell carries its tax cost (gain and, with an
   optional purchase date, short- vs long-term treatment); orders carry estimated
   transaction cost and liquidity notes; investor context now includes loss tolerance and

src/metrics.py

@@ -779,7 +779,27 @@ def candidate_fit(cand: dict, holdings: list[dict], pm: dict, risk: dict, needs:
     if needs.get("value") and isinstance(up, (int, float)) and up > 0.05:
         score += needs["value"]["weight"] * min(1.0, up / 0.5)
         fixes.append(f"trades {up * 100:.0f}% below DCF value")
+    # cautions — the guards a quant rank alone never applies (the EXPD lesson: a 94th-
+    # percentile freight forwarder at peak-cycle earnings, 18% above its 200-day, with
+    # informed money NOT accumulating, was offered as a switch destination)
+    cautions = []
+    eps_g, sma, px = live.get("eps_growth"), live.get("sma200"), live.get("price")
+    ext = (px / sma - 1) if isinstance(px, (int, float)) and isinstance(sma, (int, float)) and sma else None
+    if (sec in CYCLICAL_SECTORS and isinstance(eps_g, (int, float)) and eps_g > 0.40
+            and ext is not None and ext > 0.12):
+        cautions.append(f"peak-cycle risk: EPS +{eps_g * 100:.0f}% in a cyclical business with the "
+                        f"price {ext * 100:+.0f}% above its 200-day")
+        score -= 0.6
+    elif ext is not None and ext > 0.25:
+        cautions.append(f"extended: {ext * 100:+.0f}% above its 200-day average")
+        score -= 0.3
+    if cand.get("smart_money_neg"):
+        cautions.append("informed money is not accumulating (13F/insider score negative)")
+        score -= 0.35
     if cand.get("flags"):
         score -= 1.0
     return {"score": round(score, 3), "corr_to_book": round(corr, 2) if corr is not None else None,
-            "w_add": round(w_add, 3), "fixes": fixes[:4], "deltas": deltas}
+            "w_add": round(w_add, 3), "fixes": fixes[:4], "cautions": cautions, "deltas": deltas}
+
+
+CYCLICAL_SECTORS = {"Industrials", "Energy", "Basic Materials", "Consumer Cyclical"}

src/orchestrator.py

@@ -63,6 +63,9 @@ def _alt_candidates(holdings: list[dict], gaps: list[str]) -> list[dict]:
         # must never mint the "both signals agree" boost (the EXPD lesson: the pool's WORST
         # score once got boosted and tagged as smart-money corroboration).
         accum = {t: v for t, v in slip.items() if t not in held and v["score"] > 0}
+        for t, v in slip.items():   # a NEGATIVE score is evidence too — informed money leaving
+            if t in merged and v["score"] < 0:
+                merged[t]["smart_money_neg"] = True
         ranked = sorted(v["score"] for v in accum.values())
         for t, v in accum.items():
             pct = ranked.index(v["score"]) / max(len(ranked) - 1, 1)  # percentile among accumulators
@@ -95,7 +98,8 @@ def _enrich_candidates(cands: list[dict], k: int = 8) -> None:
         try:
             d = fetch_holding(c["ticker"])
             c["live"] = {kk: d.get(kk) for kk in
-                         ("name", "price", "sma200", "beta", "pe", "rev_growth", "div_yield")}
+                         ("name", "price", "sma200", "beta", "pe", "rev_growth", "eps_growth",
+                          "div_yield", "hi52")}
             c["flags"] = M.trap_flags(d)   # same guards holdings get (value trap, inorganic EPS…)
             price, sma = d.get("price"), d.get("sma200")
             c["trend_ok"] = bool(price and (not sma or price >= sma))
@@ -235,6 +239,25 @@ def _risk_cards(risk: dict, holdings: list[dict], context: dict | None) -> list[
     return cards
 
 
+def _candidate_brief(c: dict) -> str:
+    """The same grounded fact sheet a holding gets, framed as a prospective addition, plus
+    why the fit engine shortlisted it and any deterministic cautions."""
+    try:
+        d = fetch_holding(c["ticker"])
+    except Exception:
+        return f"{c['ticker']}: no live data"
+    pseudo = {"entry": d["price"], "pl_pct": 0.0, "weight": None}
+    up = c.get("upside")
+    dcf = ({"intrinsic": round(d["price"] * (1 + up), 2), "upside": up, "upside_vs_entry": up,
+            "lifecycle": "mechanical", "model": "mechanical DCF", "flags": c.get("flags") or []}
+           if isinstance(up, (int, float)) else None)
+    fit = c.get("fit") or {}
+    tail = "Why shortlisted: " + ("; ".join(fit.get("fixes") or []) or "quant rank")
+    if fit.get("cautions"):
+        tail += " | CAUTIONS: " + "; ".join(fit["cautions"])
+    return "PROSPECTIVE ADDITION (not held).\n" + fact_sheet(d, pseudo, fetch_news(c["ticker"]), dcf) + "\n" + tail
+
+
 _LOCAL_SYSTEM = (
     "You suggest LOCAL-market stock ideas for an investor whose portfolio is listed on a "
     "non-US exchange. Given their holdings, exchange suffix and the sectors they lack, return "
@@ -450,6 +473,29 @@ def run_analysis(rows: list[dict], emit, context: dict | None = None) -> dict:
     eligible = [c for c in scored if c["fit"]["score"] >= max(0.5 * top_fit, 0.0)]
     if len(eligible) < 3:
         eligible = scored[:3]
+    # the analyst committee screens the shortlist as PROSPECTIVE ADDITIONS — the same five
+    # lenses that judge holdings; a name they would not add is never recommended
+    if has_llm() and eligible:
+        emit(82, "Analyst committee screening the candidate ideas…")
+        short = eligible[:8]
+        cbriefs = {c["ticker"]: _candidate_brief(c) for c in short}
+        cctx = ("These are PROSPECTIVE ADDITIONS to the portfolio below — NOT current holdings. "
+                "Score each purely as a candidate to ADD now: 50 = no case to add, >=62 = worth "
+                "adding, <45 = do not add. Be as demanding as you would be with your own money. "
+                f"Portfolio: {n} holdings; sector mix " + ", ".join(
+                    f"{s} {w * 100:.0f}%" for s, w in list(pm["sector_allocation"].items())[:5])
+                + f"; what it lacks: " + "; ".join(v["label"] for v in needs.values() if v.get("label")))
+        cpanel = P.run_panel(cbriefs, cctx, samples=1)
+        for c in short:
+            sc = {k: v[c["ticker"]] for k, v in cpanel.items() if c["ticker"] in v}
+            if sc:
+                convs = [x["conviction"] for x in sc.values()]
+                c["committee"] = {"conviction": int(round(float(np.median(convs)))), "n": len(convs),
+                                  "scores": {k: round(x["conviction"]) for k, x in sc.items()},
+                                  "risks": [x["key_risk"] for x in sc.values() if x.get("key_risk")][:2],
+                                  "points": [x["key_point"] for x in sc.values() if x.get("key_point")][:2]}
+        eligible = [c for c in eligible
+                    if not c.get("committee") or c["committee"]["conviction"] >= 52]
     if has_llm():
         emit(84, "The Chief Investment Officer drafts the verdict…", chip="cio")
         cio = P.cio_synthesis({
@@ -480,7 +526,7 @@ def run_analysis(rows: list[dict], emit, context: dict | None = None) -> dict:
     # top up to >=3 new names straight from the ranked pool: without fresh names the
     # cap overflow from a concentrated book would inflate tiny existing positions
     have = {c["ticker"] for c in chosen}
-    for c in eligible:
+    for c in [x for x in eligible if REV.strong_ok(x)]:   # target-book slots need a clean bill
         if len(chosen) >= 3:
             break
         if c["ticker"] not in have:
@@ -533,9 +579,11 @@ def run_analysis(rows: list[dict], emit, context: dict | None = None) -> dict:
     sig_meta = {c["ticker"]: c.get("signals", []) for c in candidates}
     mostly_foreign = sum(1 for h in holdings if "." in h["symbol"]) > len(holdings) / 2
     fit_meta = {c["ticker"]: c.get("fit") for c in candidates}
+    com_meta = {c["ticker"]: c.get("committee") for c in candidates}
     for a in result["alternatives"]:
         a["signals"] = list(sig_meta.get(a["ticker"], []))
         a["fit"] = fit_meta.get(a["ticker"])
+        a["committee"] = com_meta.get(a["ticker"])
         if mostly_foreign and "." not in a["ticker"]:
             a["signals"].append("US-listed — needs US market access")
     result["portfolio_needs"] = needs

src/pdf_report.py

@@ -198,7 +198,10 @@ def build_pdf(res: dict) -> bytes:
             E.append(Spacer(1, 3))
         for a in alts:
             fit = a.get("fit") or {}
-            sig = " · ".join((fit.get("fixes") or []) + (a.get("signals") or []))
+            com = a.get("committee") or {}
+            sig = " · ".join((fit.get("fixes") or []) + [f"CAUTION: {x}" for x in (fit.get("cautions") or [])]
+                             + ([f"committee {com['conviction']}/100 on adding"] if com.get("conviction") else [])
+                             + (a.get("signals") or []))
             E.append(Paragraph(
                 f"<b>{_txt(a.get('ticker'))}</b> — {_txt(a.get('reason'))}"
                 + (f" <font size='7' color='#{DIM.hexval()[2:]}'>[{_txt(sig)}]</font>" if sig else ""),

src/personas.py

@@ -151,7 +151,11 @@ _CIO_SYSTEM = (
     "ALREADY RANKED by measured fit to THIS portfolio: portfolio_needs states what the book "
     "lacks, and each candidate's 'fit' block gives the specific problems it fixes ('fixes') "
     "with measured deltas (correlation to the holdings, effective positions, beta, worst crash "
-    "replay, yield, DCF gap). Prefer the top of the list; your one-sentence reason MUST name "
+    "replay, yield, DCF gap), plus — when present — 'cautions' from deterministic guards "
+    "(peak-cycle earnings, extended price, informed money leaving) and a 'committee' block "
+    "(the five analysts' conviction that it is worth ADDING, with their top risks); a "
+    "candidate with a caution or a committee risk must have it acknowledged in your reason. "
+    "Prefer the top of the list; your one-sentence reason MUST name "
     "the portfolio problem the pick addresses and cite one measured number from its fit block "
     "— never a generic 'strong company' pitch. Cite ONLY signals actually listed for that "
     "candidate. Weigh the DCF gap: a candidate far above its DCF value needs a non-valuation "

src/report.py

@@ -188,8 +188,11 @@ def _markdown(res: dict, panel: dict) -> str:
             L.append("*What this portfolio needs:* " + "; ".join(v["label"] for v in needs.values() if v.get("label")))
         for a in res["alternatives"]:
             fit = a.get("fit") or {}
+            com = a.get("committee") or {}
             L.append(f"- **{a['ticker']}** — {a['reason']}"
-                     + (f" *(fixes: {'; '.join(fit['fixes'])})*" if fit.get("fixes") else ""))
+                     + (f" *(fixes: {'; '.join(fit['fixes'])})*" if fit.get("fixes") else "")
+                     + (f" ⚠ {'; '.join(fit['cautions'])}" if fit.get("cautions") else "")
+                     + (f" · committee {com['conviction']}/100 on adding" if com.get("conviction") else ""))
     if panel:
         L += ["", "## Appendix — analyst committee detail (per holding)"]
         for r in res["holdings"]:

src/revival.py

@@ -71,12 +71,24 @@ def triage(holdings: list[dict], decisions: dict) -> list[dict]:
 
 # ---------------- switch pairs (exit → live-verified destination) ----------------
 
+def strong_ok(c: dict) -> bool:
+    """A switch destination or a target-book slot is a STRONGER recommendation than
+    'worth a look': it needs the committee clearly on side (>=58), or on side (>=52) with
+    no deterministic caution (peak-cycle, extended, informed money leaving). VLO once became
+    a switch destination at 52 with two cautions — that is not a recommendation to stand on."""
+    com = c.get("committee") or {}
+    cautions = (c.get("fit") or {}).get("cautions") or []
+    if com.get("conviction") is not None:
+        return com["conviction"] >= 58 or (com["conviction"] >= 52 and not cautions)
+    return not cautions
+
+
 def switch_pairs(holdings: list[dict], decisions: dict, candidates: list[dict],
                  needs: dict | None = None) -> list[dict]:
     """Pair each Sell/Trim with the best trend-intact candidate (candidates arrive ranked by
     measured fit to the book). Same sector first — EXCEPT when that sector is the diagnosed
     overweight, where a like-for-like swap would defeat the point of the exit."""
-    pool = [c for c in candidates if c.get("trend_ok") and not c.get("flags")]
+    pool = [c for c in candidates if c.get("trend_ok") and not c.get("flags") and strong_ok(c)]
     overweight = str(((needs or {}).get("sector_overweight") or {}).get("sector") or "")
     used, pairs = set(), []
     exits = sorted((h for h in holdings if decisions[h["symbol"]]["action"] in ("Sell", "Trim")),
@@ -107,6 +119,9 @@ def switch_pairs(holdings: list[dict], decisions: dict, candidates: list[dict],
             "in": cand["ticker"], "in_name": live.get("name") or cand["ticker"],
             "sector": cand.get("sector"), "same_sector": cand.get("sector") == sec,
             "cross_market": cross_market, "signals": signals,
+            "fixes": (cand.get("fit") or {}).get("fixes") or [],
+            "cautions": (cand.get("fit") or {}).get("cautions") or [],
+            "committee": cand.get("committee"),
             "compare": {"out": _snap(h["data"], h["data"].get("price")),
                         "in": _snap(live, live.get("price"))},
         })

static/app.js

@@ -377,9 +377,13 @@ function renderResults(R) {
     const tags = (a.signals || []).filter(s => s.includes("smart") || s.includes("quant") || s.includes("local") || s.includes("US-listed")).map(s =>
       `<span class="sig">${esc(s.includes("smart") ? "🐋 smart money" : s.includes("quant") ? "🧮 quant rank" : s.includes("local") ? "📍 local market" : "🇺🇸 US-listed")}</span>`).join(" ");
     const fit = a.fit || {};
-    const fixes = (fit.fixes || []).map(f => `<span class="fix">✓ ${esc(f)}</span>`).join(" ");
+    const fixes = (fit.fixes || []).map(f => `<span class="fix">✓ ${esc(f)}</span>`).join(" ") +
+      (fit.cautions || []).map(f => `<span class="caution">⚠ ${esc(f)}</span>`).join(" ");
+    const com = a.committee;
+    const comLine = com ? `<div class="committee">Committee ${com.conviction}/100 on adding it` +
+      ((com.risks || []).length ? ` · top risk: ${esc(com.risks[0])}` : "") + `</div>` : "";
     av.appendChild(el("div", "alt", `<b>${esc(a.ticker)}</b> ${tags}<p>${esc(a.reason)}</p>` +
-      (fixes ? `<div class="fixes">${fixes}</div>` : "")));
+      (fixes ? `<div class="fixes">${fixes}</div>` : "") + comLine));
   }
   // recommended target portfolio (only when the user gave context)
   const target = R.target_portfolio || [];

static/style.css

@@ -166,6 +166,8 @@ button, .primary { font: inherit; cursor: pointer; border-radius: 10px; }
 .needs-line b { color: var(--text); }
 .fixes { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
 .fix { font-size: .74rem; color: var(--good); background: #2fbf7118; border: 1px solid #2fbf7144; border-radius: 6px; padding: 2px 8px; }
+.caution { font-size: .74rem; color: var(--warn); background: #e8a83818; border: 1px solid #e8a83844; border-radius: 6px; padding: 2px 8px; }
+.committee { color: var(--dim); font-size: .78rem; margin-top: 8px; }
 .risk-body h4 { font-size: .78rem; color: var(--accent2); text-transform: uppercase; letter-spacing: .07em; margin: 4px 0 8px; }
 .risk-line { color: var(--dim); font-size: .88rem; line-height: 1.5; margin: 8px 0; }
 .risk-line b { color: var(--text); }

tests/test_recommend.py

@@ -82,6 +82,30 @@ def test_switch_pairs_avoid_overweight_sector():
     assert switch_pairs(hs, dec, cands, {"sector_overweight": {"sector": "Technology"}})[0]["in"] == "ED"
 
 
+def test_peak_cycle_and_smart_money_guards():
+    hs = [{"symbol": "AAA", "weight": 1.0, "data": {}}]
+    pm = _pm(sector_allocation={"Technology": 1.0}, effective_n=1.0)
+    needs = M.diagnose_needs(pm, {}, [], None)
+    clean = {"ticker": "X", "sector": "Industrials", "rank_pct": 94, "signals": [],
+             "live": {"eps_growth": 0.08, "sma200": 100.0, "price": 104.0, "beta": 1.0}, "upside": 0.0}
+    expd = {"ticker": "X", "sector": "Industrials", "rank_pct": 94, "signals": [], "smart_money_neg": True,
+            "live": {"eps_growth": 0.51, "sma200": 158.0, "price": 186.0, "beta": 1.0}, "upside": 0.0}
+    fc = M.candidate_fit(clean, hs, pm, {}, needs, None, None)
+    fe = M.candidate_fit(expd, hs, pm, {}, needs, None, None)
+    assert fe["score"] < fc["score"] - 0.9
+    assert any("peak-cycle" in c for c in fe["cautions"]) and any("informed money" in c for c in fe["cautions"])
+    assert fc["cautions"] == []
+
+
+def test_strong_ok_requires_clean_committee_verdict():
+    from src.revival import strong_ok
+    assert strong_ok({"committee": {"conviction": 64}, "fit": {"cautions": ["peak-cycle"]}})
+    assert strong_ok({"committee": {"conviction": 52}, "fit": {"cautions": []}})
+    assert not strong_ok({"committee": {"conviction": 52}, "fit": {"cautions": ["peak-cycle"]}})
+    assert not strong_ok({"committee": {"conviction": 45}, "fit": {}})
+    assert strong_ok({"fit": {"cautions": []}}) and not strong_ok({"fit": {"cautions": ["extended"]}})
+
+
 def test_candidate_fit_flags_penalized():
     hs = [{"symbol": "AAA", "weight": 1.0, "data": {}}]
     c = {"ticker": "X", "sector": "Energy", "rank_pct": 99, "signals": [], "live": {}, "flags": ["VALUE_TRAP"]}