What pit-boss is, from the ground up

pit-boss is a small, careful robot that copies the stock picks of one professional investor, four times a year, using the investor's own public paperwork. Before it is allowed to buy or sell anything, a strict set of written rules — the house rules — checks every order and shrinks or refuses anything too big, too concentrated, or too risky. Then a locked gate asks for proof that a human read the exact list of orders (or that the exact list has already been rehearsed successfully). Only then does anything reach a broker. Everything it does is written down permanently, so that any decision can be reconstructed later from the written record alone.

Today it trades a paper account — pretend money at a real broker (Alpaca), with real prices and real order handling but no dollars at risk. It has never traded real money and it is not yet allowed to.

In a casino, the pit boss is the person who does not gamble. They stand at the edge of the floor, watch every table, know the house rules by heart, and say "no" when something is out of bounds. They are not there to make the game exciting; they are there to make sure the game is played correctly.

That is this system's job. The exciting part — picking stocks — is outsourced to someone else entirely (the investor whose filings we copy). What pit-boss adds is supervision: the limits, the gate, the ledger, the alarms. That is why the dashboard looks like a ruled ledger rather than a trading screen, and why an approved order is drawn as almost nothing (a small dot) while a refusal is drawn as an inked stamp. On a healthy day the page is nearly blank. Ink is spent only where the house pushed back.

The Python package underneath is called house_rules, for the same reason. The rules are the product; the strategy is a plug-in.

In the United States, any investment manager who controls more than $100 million of stock has to tell the government what they own. They do this by filing a form called a 13F with the SEC (the Securities and Exchange Commission), once every three months. The form lists every stock position they held on the last day of the quarter: the company, how many shares, and what it was worth.

Three details matter enormously for what we do with it:

• It is late on purpose. A manager has up to 45 days after the quarter ends to file. So the picture we get is at least six weeks old by the time we can see it. Most managers file right at the deadline. Ours files about 44–45 days after quarter end, so the filing lands mid-February, mid-May, mid-August and mid-November.
• It only shows long positions and some options. A 13F shows what a manager owns. It shows put and call options too, but only as a face value ("notional") with no strike price, no expiry, and no size that can be copied. It never shows short positions. So the form is a keyhole view, not the whole room.
• It is public and free. Anyone can download it from the SEC's EDGAR system. There is nothing secret or privileged in what pit-boss reads.

The academic finance literature has studied "cloning" 13Fs for decades. The honest summary: copying a genuine stock-picker's concentrated, high-conviction long positions, right after the filing lands, has shown a modest edge — single digits per year — that survives the 45-day delay. Copying options does not work (they cannot be sized). Copying one manager rather than a consensus of several is the riskiest version of the idea. pit-boss does the best-evidenced version and treats the risks as first-class.

The filer we follow is Situational Awareness LP, a hedge fund whose 13Fs show a concentrated book of AI-infrastructure and semiconductor names, alongside a very large book of put options that we cannot copy. From each new filing, pit-boss computes a target portfolio in exactly these steps, and the steps are deterministic: the same filing always produces the same targets, byte for byte, and a script in CI re-derives every committed target from the archived filing to prove it.

1. Strip every option line. Puts and calls are logged as "context: hedges we can see but not size" and never traded. What remains is the common-stock long book.
2. Apply the conviction filter. Keep only positions that are at least 2% of that stock-only book, and at most the top 10 by weight. Small positions are noise; the edge in the literature comes from the manager's biggest bets.
3. Resolve each line to a tradeable ticker. The filing identifies stocks by CUSIP (a nine-character security ID). If a CUSIP cannot be resolved to a ticker — a delisting, a merger, a bond CUSIP used for a stock — the line drops to cash with a logged reason. It is never guessed. (A committed, reviewed override file can supply a ticker for a known case, and every override must carry evidence, an approver and a date.)
4. Renormalize. The surviving weights are scaled so they add up to 95%, leaving a 5% cash buffer.
5. Write the artifact. The result is a targets document listing every held name with its filing weight and its target weight, every excluded line with the reason it was excluded, the accession number of the filing it came from, and the exact configuration that produced it. If the filer later amends the filing, the old targets are marked superseded and the amendment wins.

That is the entire "strategy". There is no forecasting, no indicator, no news-reading. Once a quarter the target book changes because the filer's book changed, and the system trades the account from where it is to where the targets say it should be — subject to the house rules below.

A lot of the design is negative space. These are decisions, not gaps:

• No option cloning. The filing does not give enough to size them.
• No signal mining. No "try a hundred ideas and keep the one that worked" — that produces fake edges by construction.
• No Kelly sizing. Six filings are not enough data to estimate a win/loss distribution; sizing is fixed against the limits.
• No fully autonomous, unattended, "confirmation off" trading of real money. The gate below is not a setting.
• No language model in the money path. An AI can run scripts and read reports; it cannot compute a position, approve a risk check, or place an order. (More on this below.)
• No unofficial broker APIs, no screen-scraping, no scraped market data.
• No live trading yet, at all. The broker adapter has paper=True written into it. Passing --live is refused rather than quietly running paper, because someone would draw live conclusions from a paper run.

A "rebalance" is the once-a-quarter act of moving the account from what it holds to what the new targets say. Here is the whole path from the SEC's website to a filled order, in order. The order is itself a safety property: nothing later in the list can happen until everything earlier has succeeded. Under each step is what makes it stop.

The limits live in one version-controlled file, src/house_rules/risk/limits.yaml. There is no environment variable, command-line flag, or runtime setter that can loosen one. Changing a limit takes a commit and a review, and the review ritual allows at most one rule change per quarterly cycle. A self-test (hr-risk-check --demo) pushes deliberately violating trades through the engine and fails if any get through; it runs in CI so a bad build cannot merge.

The original rule was "nothing reaches a broker without a human typing a phrase". Looked at closely, the phrase was never the point. The real property is:

An order cannot be submitted unless a capability token exists that is bound, by fingerprint, to the exact plan being submitted.

The submit function takes a token object, not a yes/no. There are three things that can mint one, and the executor does not care which:

1. A phrase typed at a real terminal. Running hr-rebalance prints the full plan and waits for you to type CONFIRM REBALANCE <QUARTER> exactly. Piped input is refused, so no script can type it for you. Anything else aborts the plan.
2. A phrase typed on the dashboard. The web version proves the same four things the terminal did, each failing closed: identity (a signed-in, email-verified Google account on the allowlist), binding (the browser echoes the fingerprint of the plan it rendered, and it must match the stored one), presence (the exact phrase, typed — the input refuses paste), and freshness (the plan expires 20 minutes after it was built; a walked-away operator has not confirmed). The stored plan is the confirmed plan; it is never rebuilt at confirm time, because prices move and you would be confirming words you never read. Building a new plan supersedes any older one still waiting, so the phrase can only ever apply to the newest thing you read. The status flip from "awaiting" to "submitting" happens in a database transaction, so a double-click or a second tab cannot submit twice.
3. A paper proof. The identical plan is first executed against a paper account: every approved order submitted, none rejected, nothing left in flight, every fill settled, and post-trade reconciliation with zero breaks. Only then is a PaperProof minted, and it expires after 30 minutes. There is no partial proof, because there is no partially authorized order: a rejected paper order is evidence the live run would meet the same refusal. A proof cannot be minted against a live venue (that would place real orders in order to authorize placing real orders). This is the token the autonomous path uses; the human moves from approver to overrider — and is notified when a proof is minted and when it is spent, because an override nobody knows to use is not an override.

The one switch is halt. Locally it is a file named halt in the repo root; in the cloud it is the Firestore document ops/halt, toggled by the "Halt trading" button on the dashboard. It is checked before a proof runs, between every paper order, and between every live order. Setting it stops the run at the next boundary and preserves the plan; clearing it is equally deliberate. It is reachable from a phone.

Everything the system decides is appended to a journal: runs, plans (including blocked orders and why), every order state transition (planned → approved → confirmed → submitted → partially filled → filled / cancelled / rejected / expired), every fill, equity points, and free-text notes. It is append-only. When something goes wrong you fix it by adding a record — a missing fill, a correcting note — never by editing history. The design goal is that any past decision can be reconstructed from the artifacts alone, without trusting anyone's memory.

There are two journals, and it matters which is authoritative:

• The local journal (journal/journal.sqlite) is where the system was born and where the intraday session engine, tear-sheets and the trial registry still write.
• The cloud journal (Firestore collections prefixed journal_) is where the web-gated and autonomous rebalance write, and since the first cloud rebalance ran it is the system of record for the paper account. The mirror from local to cloud is one-way, deliberately, so there is never a question of which record wins — and there is no cloud-to-local backfill. Once the cloud has traded an account, the local journal for that account is permanently behind, and running the local rebalance against it would be running over a history it does not know.

A useful consequence: every order this system has ever placed carries a client order ID beginning hr-. Any order in the account without one was not placed by pit-boss, and reconciliation will say so.

The same Python package runs in two places. On a laptop it is a set of hr-* command-line tools (see the FAQ for the list). In the cloud it is a Firebase project: static Hosting for this dashboard, Firebase Auth in front, Firestore as the journal, Python Cloud Functions running the scheduled jobs, and Google Secret Manager holding the broker keys — the keys are injected into functions and never appear in the repo, in logs, in Firestore, or in the browser. The functions vendor the exact same house_rules package at deploy time, so cloud parsing is byte-identical to local parsing.

The Firestore security rules refuse every write from a browser; only functions write, through the Admin SDK. Reading requires a signed-in, verified Google account on an allowlist, and every function that can move toward an order re-checks that same allowlist server-side. "Signed in with Google" alone is not authorization.

The page you land on after signing in is called the house ledger. Read it top to bottom and it answers one question at a time. (The FAQ goes deeper on reading each panel.)

• Account equity and its sparkline; cash; position count; the last rebalance. The number is the last recorded snapshot, not a live tick.
• House limits — up to four gauges (largest position, invested, drawdown, planned turnover): how much of each limit is spent, with the cap drawn as a hard stop so "how close" is visible rather than inferred.
• The ledger — every rule's verdict on every order in the latest plan. A dot is an approval; a stamp is a reduction or a block. This is the signature of the whole system: nothing else records the rules that did not bind.
• The gate — build a plan; read it; type the phrase; or halt trading.
• Book against targets — what the broker says you hold versus what the targets say, with drift.
• What the clone leaves behind — how much of the filing the clone reproduces and how much it discards (the options), and whether the filer is short a name we are long.
• Capital not deployed — structural "leaks": cash buffer, whole-share rounding, names dropped for lack of a ticker, price paid versus intended.
• When this filer files, Clone decay, Reconciliation, Per-quarter scorecard, What the limits cost (recorded equity against the same filings replayed with no limits), Evidence (the validation battery's ruling), and Filings.

Every panel owns its own empty state. A panel that cannot be computed prints the reason; it never draws a zero, because with no trade history "no data" and "no drift" would otherwise look identical. Small samples wear a n=3 of 20 tag on the face of the number.

A language model (Claude Code, mostly) is the operator of this system: it runs the scripts, reads the reports, drafts journal entries, and writes code. It is never the calculator. No model output touches position math, a risk check, or an order. The reason is not caution for its own sake: a systematic review of LLM-agent trading found the field's performance claims essentially unreproducible, and red-team studies show that misinformation planted in an agent's data feed changes its trading decisions a quarter of the time. Keeping the model out of the decision path entirely is the only architecture the evidence fully supports.

There is one place a model may influence the book, and it is bounded arithmetically. An optional LLM operator can propose adjustments to a target portfolio before the risk engine sees it — but the only two actions it has are exclude a name and tilt a weight down. It cannot add a name the filing does not contain, cannot raise any weight, cannot touch a limit, and freed weight goes to cash. A maximally adversarial model can only make the book more conservative than the mechanical clone. Its bounds are enforced by code (the prompt merely states them as a courtesy); an out-of-bounds proposal is refused whole, never clamped; and the raw proposal, the model identity, the prompt fingerprint and a written rationale per adjustment are journaled verbatim, because you cannot re-derive what a model would have said. By default the operator proposes nothing and the trading path makes no model call at all.

The same core (risk engine, journal, adapters, dashboard) also hosts a second, opposite-cadence feature: intraday day trading inside a human-confirmed session envelope. Before the open, a human confirms a session — strategy and version, symbol whitelist, maximum position size, a hard daily loss limit, allowed time window, blackouts around scheduled macro events — by typing a phrase. Deterministic code trades inside that envelope; the envelope cannot be altered once armed; three consecutive out-of-envelope orders kill the session; everything is flattened by a hard cutoff before the close; and an independent dead-man supervisor cancels and flattens if the process stops heartbeating for 60 seconds. Every strategy input is captured to hash-sealed files so a session can be replayed exactly.

The evidence posture here is adversarial: the academic base rate for retail day trading is poor, so no intraday strategy touches real money until it has earned it on paper through a formal validation battery — at least 60 sessions or 300 trades, positive out-of-sample walk-forward, and a probability-of-backtest-overfitting / deflated-Sharpe pass over every variant ever tried (each registered before it is tested, so the denominator is honest). Failing the battery kills the strategy; that outcome is expected for most candidates and is the system working. As of now the first candidate (an opening-range breakout) has no evidence of edge and no paper season has been run.

A few ideas about evidence run through everything, and they explain why the dashboard sometimes tells you unflattering things.

• Beating the market is not the claim. The book has a beta of roughly 3.6 to SPY — it moves more than three times as much as the index — so "beat SPY" is nearly meaningless as a skill claim; leverage would do it. The narrower claim the strategy makes is that the conviction filter and timing add something over a naive clone (the same names, equal-weight, bought at period end and held). The tear-sheet reports both, and also against SMH (the semiconductor ETF), which is the honest comparison for a book this concentrated.
• Small samples are labelled, not hidden. Under about twenty observations the tear-sheet withholds ratios; where it reports one, the 95% confidence interval sits beside it, and on a short history that interval is wider than any plausible skill.
• The quarterly strategy failed its own battery. Replaying the archived filings through the system produced a big headline return — and a 47% peak-to-trough drawdown against a 25% circuit breaker. At 47% the breaker trips, every buy is blocked, and a manual re-arm is required. The headline assumes a book the system's own rules forbid. The verdict is on the dashboard's Evidence panel and it is not being tuned around: choosing parameters because their column looks best is precisely the trap the whole product is built to avoid.
• Costs are charged. Paper results only count net of modelled commission and slippage; a strategy whose edge disappears under costs fails.

• Paper only. No live trading, no money at risk. The Alpaca adapter hard-codes paper; the live arming path has no web equivalent and is not built for any real venue.
• The cloud is the trading path. The web gate has planned, confirmed and submitted a real rebalance on the paper account, and the cloud journal is now the system of record for it. Its exit criterion — one rebalance through the web gate with clean reconciliation in one run, with no hand repair afterwards — has not yet been met, so the local scheduled jobs have not been decommissioned. The local hr-rebalance must not be run against the paper account any more.
• Autonomy is built and disarmed. The autonomous cycle is deployed but ops/autonomy is not set, so a new filing queues a cycle and sends a notification instead of trading. Note also that in the current cloud deployment the paper-proof leg and the "live" leg point at the same paper account, which makes the proof vacuous — the code says so loudly, and a second account is needed before autonomy demonstrates anything.
• The Q2-2026 filing landed on 14 August 2026. The next real cycle is that one. What to do about it is the first question in the FAQ.
• The quarterly strategy has failed the validation battery on drawdown; the intraday strategy has no evidence of edge and no paper season yet. Neither is approved for live use.
• What must be true before any real dollar: two clean paper cycles with tear-sheets and journal entries; tax-lot and wash-sale accounting; a validation verdict that is not FAIL; and a written, journaled decision.

The FAQ covers how to actually use it day to day, and what to do when it pushes back.