[design·P1] What does this product mean by risk? Structure at one instant is the whole current answer, and the owner's definition includes what is about to happen to it

[atomchung]

Privacy boundary

Public design leaf. No real data.

The question this issue exists to settle

The product currently answers "how risky is this book?" entirely with structure
at one instant: weights, top-N concentration, driver share, sector share,
distance from a sizing cap. Every one of those is a fact about how the book is
shaped today.

Asked directly what should be watched, the owner rejected that as the whole
answer:

let's think about what risk actually is. For a holding, what is risk? It also
has to combine future market observation. For example, what earnings are coming
up that could affect what? What is the recent market momentum like?

That is a different definition: risk as structure × what is about to happen to
it. A concentrated position ahead of a scheduled catalyst and the same position
in a quiet window are the same number and not the same risk, and the product
currently cannot tell them apart.

Why this is a definition question, not a feature request

It would be easy to read this as "add an earnings calendar". That is the wrong
frame and would produce a generic market recap bolted onto a card — the outcome
the market-lookup contract already exists to prevent.

What has to be settled first is what the product means by risk, because that
decides everything downstream:

• If risk stays structural, then "what should I watch" is out of scope and the
  card should say so rather than leave the reader to infer it.
• If risk is structural exposure plus its near-term catalysts, then the standing
  packet idea already deferred in [feat·P1] A weekly review should read the week's market against the user's own holdings — prices, turning points, not only an index delta #683 is the mechanism, and the bounded lookup
  contract governs what may be fetched.
• If risk is a per-position property rather than a book property, the
  instrument-level surface has to carry it, which is a different rendering
  problem again.

Boundaries that hold whichever way it is settled

• No price target and no market forecast. A scheduled event is a fact; what it
  will do to the price is not.
• A found public event never becomes the user's motive without their
  confirmation.
• Nothing here permits naming what to buy or sell.
• Continuous background collection stays out; this is decision-time lookup, and
  that boundary was already settled.

Acceptance criteria

• A recorded definition of risk for this product, in one paragraph, that a later
  reader can hold a surface against.
• For each route, a statement of which half of that definition it delivers and
  which it withholds, so silence is never left to interpretation.
• If forward-looking catalysts are in scope, the first slice is bounded the way
  [feat·P1] A weekly review should read the week's market against the user's own holdings — prices, turning points, not only an index delta #683's was — a stated trigger, a stated omission rule, no persistence — rather
  than an open-ended market feed.

Related

• [design·P1] The market read is bound to weekly_review, so the holdings-only cold-start user — the one its gate was written for — can never receive it #772 — the market read never reaches a holdings-only user; this issue is the
  layer above it, asking what that read is for.
• [feat·P1] A weekly review should read the week's market against the user's own holdings — prices, turning points, not only an index delta #683 — the shipped weekly companion and its deferred standing-packet half.
• [card·design·P3] A period-local section would earn the short-window market comparison back #366 — a period-local section and the short-window market comparison.

[atomchung]

Owner ruling — 2026-08-02: risk includes what is about to happen, and that is the core

The owner ruled directly on the question this issue exists to settle:

Does risk include forward-looking catalysts? Yes — and that is what people actually care about. The forward-looking catalyst is the core concern.

This is now the recorded definition of risk for the product. Structure at one instant — weights, concentration, sector share, distance to a cap — is no longer the whole answer. It is the filter that decides which forward-looking events matter to this particular user.

What the ruling settles

1. A risk answer that describes only current structure is incomplete, not merely terse. Two books with identical concentration are not equally risky if one of them has an earnings print next week.
2. The recorded book's job shifts. It stops being the output and becomes the selector: it is what makes a forward-looking read personal rather than a generic market feed. This is what distinguishes the product from a news app.
3. This extends, and does not contradict, the 2026-07-25 shape decision that moved the product's centre of gravity to the decision moment.

The line that does not move

Boundary 2 in AGENTS.md is unchanged and now does most of the work:

• A dated, published fact is in. "This company reports on 2026-11-20." "This index rebalances on the 19th." "The lockup expires next month."
• A forecast, a price target, or a market prediction stays out. "This print will beat." "This is going to 200." The product states what is scheduled, not what will happen.
• A found public event never becomes the user's motive without their confirmation.

The whole value of the ruling survives inside that line: knowing that a catalyst is dated inside a concentrated position is decision-relevant on its own. Predicting its outcome is not the product.

Deterministic first — this is a design constraint, not a preference

A meaningful share of "forward-looking catalyst" is deterministic data, not research: scheduled earnings dates, index events, ex-dividend dates, lockup expiries. Anything that can be retrieved deterministically must enter through the engine and carry a validator.

The reason is recorded evidence, not taste. #782 established that the engine's numbers pass gates while the agent's own sentences pass none — three output-voice violations shipped in one owner-live session with a fully green trace. Routing forward-looking content through the narrated lane by default would put the product's newest and most hallucination-prone content on its only ungated surface.

So the ordering constraint is: the live voice/answer gate owed by #782 lands before the researched half of this capability opens. The deterministic half does not have to wait for it.

Interpretation flagged for correction

The owner's words were "历史的东西都不重要了" — the historical material no longer matters. Recorded above as: history stops being the output and becomes the selector. It is not read as a mandate to remove the transaction-history routes, the review card, or the recorded book, which are what make the forward-looking read personal at all. If the intended reading was stronger than that, this section is the thing to correct.

Cascade

Unblocked by this ruling, and to be re-scoped against it: #772 (which of three market-read shapes), #780 (driver taxonomy depth), #776 (one route-scoped market-context capability), #683 (the week's market read against the user's own holdings).

Blocking prerequisite for the researched half only: #782.

[atomchung]

Owner refinement — 2026-08-02: why history matters less, stated correctly

The owner corrected the previous comment's reading. "历史的东西都不重要了" was an overstatement, and the interpretation recorded above — history becomes the selector — is not the reason either.

The owner's actual reasoning:

Whatever history holds is already reflected in the current price. What is not yet in the price is future news. That is where attention belongs. For the agent, both still have to be judged.

What this changes

The previous comment justified keeping history on the grounds that it tells the product which events matter to this user. That is true but secondary. The primary job is different:

History is the baseline against which an upcoming event is judged as a surprise or a non-event. An earnings date inside a concentrated position is not automatically risk — it is risk to the degree the position's current price does not already reflect it. Without the recorded history the agent cannot make that call at all; with it, the call is possible but it is a judgment, not a fact.

So re-narrating history for its own sake has low marginal value — that is the real content of the ruling — while history as the input to a forward judgment is load-bearing.

The division of labour this implies

Layer	Owns	Gate
Engine	Dated facts, both directions: cost basis, entry, realized/unrealized, weights and scheduled earnings, index events, ex-dividend, expiries	Validator, fail-closed
Agent	Whether an upcoming dated event is a surprise relative to what the record already shows	Marked as its own judgment, anchored to an engine fact (boundary 2)
Out	Price targets, outcome predictions ("this print will beat"), market forecasts	Refused

The agent judging "is this already in the price?" is inside boundary 2, not an exception to it: boundary 2 already requires every claim the agent adds to be marked as its own judgment and cited to an engine fact through the documented anchor. What stays refused is the outcome of the event, not the assessment of whether it is anticipated.

Correction to the record

The table above supersedes the "history stops being the output and becomes the selector" line in comment 5156514056. That comment's two hard constraints — dated fact in / forecast out, and deterministic-first — are unchanged and still carry.

[atomchung]

Correction to this ruling's own facts — measured, 2026-08-02

The "deterministic first" constraint recorded above listed scheduled earnings dates, index events, ex-dividend, lockup expiry as the deterministic set. Two of those four are wrong. Measured against the provider the engine already uses, independently reproduced by the orchestrator:

Forward fact	Deterministic?
Scheduled earnings date (earningsTimestampStart, with isEarningsDateEstimate telling confirmed from estimated)	Yes — US and TW equities, ADRs
Ex-dividend / dividend-pay date	Yes
Index events (add/drop, rebalance)	No — not carried at all
Lockup expiry	No — not carried at all

Index events and lockup expiries are therefore researched facts, not deterministic ones. Under this ruling's own ordering they fall behind the live answer gate owed by #782, together with the rest of the researched half.

The scope fact this ruling has to carry: ETFs have no forward coverage

SPY, QQQ, VT, ^GSPC return none of the four fields. A book held entirely in broad-market ETFs — the exact shape #715 exists to support — gets zero forward-dated content from the deterministic lane. Whatever this capability delivers must state that absence rather than render an empty section, or the user reads silence as "nothing is coming".

Why the boundary must be an allowlist, not a filter

The same provider call that returns the earnings date also returns, in one response:

NVDA     targetMeanPrice: 302.83   recommendationKey: "strong_buy"
2330.TW  targetMeanPrice: 3117.26  recommendationKey: "strong_buy"

A price target and a buy recommendation — the two things boundary 2 refuses outright — arrive in the same payload as the fact this capability wants. A "strip the forbidden keys" filter fails open the moment the provider adds a field. The acquisition layer must copy a closed list of named keys and discard the rest unread. This is not a style preference; it is the difference between a boundary that holds and one that holds until the next provider release.

Measurement and full design: #776 comment 5156586064.

[atomchung]

Owner ruling — both halves together; macro is a shared layer

Recorded in full at #776 comment. Two points that bear on this ruling's own definition:

1. Option B: the company-dated facts and the macro calendar ship as one capability. [process·voice·P2] A live consider answer passes through no voice check — three output-voice violations shipped in one owner-live session with a fully green trace #782's live answer gate is therefore a hard prerequisite for the whole thing.
2. 總經也是個股的催化劑 — macro events are catalysts for single-name holdings, not only for broad-market ETFs. The earlier framing that assigned macro to the all-ETF case is superseded; it is a shared layer over every holding, and the all-ETF book is just the case where it is the only layer available.