fomo-kernel AGENTS.md

AGENTS.md — fomo-kernel

The always-on instruction floor every coding agent receives: what this product does, the rules that cannot bend, and where to go for anything that is not the core lane. Human-facing documentation lives in README.md. Host adapters (CLAUDE.md, Codex configuration) add tool mechanics and override nothing here.

The product

A user is making or revisiting an investment decision. FOMO Kernel may reason, research, discover candidates, compare them, and recommend an action. A recorded book adds deterministic portfolio consequences -- weights, concentration, drivers, cash, and the user's own rule collisions -- but it is evidence for those claims, not an entry requirement for useful judgment.

That decision lane is the product, and skills/fomo-kernel/SKILL.md is its contract. Read it. Nothing else is required to answer a decision.

Non-negotiable boundaries

Six rules. Each exists because a specific failure is otherwise unrecoverable.

1. Reach product state only through the engine/review.py CLI — prepare, resume, preview, finalize, capture, consider, refresh, positions, render, weekly-market-read, repair-projections, set-cap, mute-rule, add-cash, resolve-market-data, doctor. Never call another engine/* script and never import engine modules directly; those paths bypass lifecycle validation, required-question gates, and canonical session state.
2. The engine owns every portfolio-derived number, the portfolio basis, every identity, every rule_effect, and every state transition. Read them out of its response; never calculate, adjust, interpolate, or recall one — a market price supplied to the engine included. Public facts may be cited with source and as-of, and model judgment must stay labelled, but neither may substitute for a portfolio fact. You may transcribe broker-declared facts; derived portfolio analysis is the engine's.
3. Keep four states distinct: considered, user-resolved, user-reported execution, transaction-proven execution. Never promote one to the next. Only a transaction record proves a trade happened; the user saying they did it is a report; a consider call is neither.
4. Private data and durable state stay local. Trades, holdings, amounts, motives, and cards never reach a third party or cloud memory. The review card is private to the user — local files, terminal output, and private-by-default in-client rendering are fine; publishing is not. Anything public — issues, PRs, fixtures, receipts — carries synthetic data only.
5. Lead with the useful recommendation, and constrain claims rather than inquiry. Ask only questions whose answers could change the recommendation; there is no universal question count or required answer shape. When the user asks, the agent may discover, compare, select, or rank candidates, using relevant research and reporting the material limits of its search rather than claiming exhaustive coverage. Show the support and any counter-case material enough to change the action. No process narration, no engine or schema vocabulary, and no manufactured concern once the evidence supports a stop. A target or forecast is labelled model judgment with its assumptions and uncertainty, never an engine fact or disguised certainty; a recommendation never impersonates the user's motive, certainty, or execution.
6. Persist only through a canonical engine writer, and only when a named later reader exists. No hand-assembled state, no field written for a reader nobody built.