[feat·M2] Append-only rationale refresh anchored to a position cycle

[atomchung]

Status

Owner-approved active implementation front, 2026-07-31. May proceed in parallel with #610.

#610 remains the frozen M1 judgment-quality dogfood lane. This issue is a separate M2 memory vertical slice: continuing-position self-report, not TradeEvaluation answer quality. Development may proceed on isolated branches while #610 runs against its frozen SHA. Do not merge a consider consumer into the #610 candidate mid-walk.

Milestone

M2 — Recall and Compare My Reasons.

This is a narrow owner-approved exception to #475's earlier sequencing gate. It does not unlock broad M2: #636 DecisionIntent, #490 execution linkage, #609 prior-evaluation recall, profile distillation and rule learning remain separately gated.

User outcome

A user can state or update why they currently hold a recorded position without running a review:

「我現在繼續持有 X，是因為 Y。」

FOMO Kernel records the exact words locally, returns a short receipt, and the next relevant review starts from that statement rather than asking from zero.

The same canonical writer is used when the statement arrives through:

1. direct chat / standalone CLI entry;
2. a review rationale-refresh question;
3. the existing light-capture route.

A review is a reader and selective collector, not the aggregate root of the rationale.

Current behavior / evidence

Verified on main@9d56a2d:

• review.py capture is not a standalone user entry. It requires a pending light-tier Review Plan, cycle ids already exposed by that plan, and consumes the pending session.
• The light path writes thesis_decision.note; thesis.reconstruct_states can fold the bytes into thesis state, but [process·gate-debt] Disposition tracker: 34 fields the deepened QUESTION_CONSUMERS field-level check found unread across 4 sinks #480 records that this user-authored note has no guaranteed visible card reader.
• theses.jsonl is documented as rebuildable compatibility state. Generalizing its direct append path would create a second canonical truth outside immutable sessions.
• Full reviews collect several adjacent motive forms (initial_thesis, add-decision note/evidence, headline_motive, inferred thesis), but [design·P1] Two questions collect an answer nothing reads: initial_thesis and exit_consistency (proved by a byte-identical card) #429/[process·gate-debt] Disposition tracker: 34 fields the deepened QUESTION_CONSUMERS field-level check found unread across 4 sinks #480 prove that collection and future consumption are uneven.
• Snapshot-derived cycle identity is not stable across ordinary declarations ([bug·design·P2] Every new snapshot declaration re-asks for theses it was already given #539), and review-lane adoption can spend previously captured holding provenance ([bug·design·P2] A review-lane anchor adoption spends the user's holding-duration answer #536). A rationale attached to such an identity would appear remembered and then silently disappear.

Domain decision

1. One object: PositionRationale

This issue owns why the user says they currently continue to hold one active position cycle.

It does not own:

• a proposed trade's reason ([feat·M1] Bounded TradeEvaluation with visible two-sided challenge #479/[feat·M2] DecisionIntent memory — automatically record a live trade intent, then resolve it from execution evidence or one follow-up #636);
• proof that an action executed ([feat·M2] Explicit execution link promotes an evaluation into durable decision memory #490);
• a behavior-derived profile label or behavior/self-report verdict ([design·P1] The distillation layer: bounded profile memory over the append-only ledger (scoping) #446);
• a standing rule ([design·P1] A rule is the user's own standing expectation, not a review output — the loop, and what currently forces it through one door #650).

Changed wording is evidence, not automatically drift, dishonesty or rationalization.

2. One canonical stream

Add a dedicated canonical append-only stream:

<root>/position_rationales.jsonl

with one schema and one module owning validation, append, fold and bounded query. theses.jsonl remains a rebuildable thesis projection / agent interpretation source and is not the canonical home of direct user wording.

Register the stream with data-status, export and reset. Corruption, conflicting duplicate identity and partial writes fail closed. Append uses the existing root write lock plus flush/fsync discipline; no second lock hierarchy.

3. Event contract

The first schema carries at least:

• schema_version;
• engine-assigned event_id, content-addressed from the stable payload and excluding recorded_at;
• subject: active cycle_id, ticker, market and currency facts resolved by the engine;
• change: initial | changed | no_change;
• exact user_statement, byte-for-byte for initial / changed;
• continues_event_id for no_change, so the prior substantive wording remains the effective statement without being copied or rewritten;
• stated_at for when the statement applies and canonical recorded_at for append time;
• voice: user_verbatim;
• capture_source: direct | review | light_capture plus the producing interaction/session id when one exists;
• the recorded-book state_version used to resolve the active subject;
• mapping_status: mapped | unmapped and an optional condition reference when a later slice legally creates one.

A first statement is initial, never falsely labelled changed. Exact retry is a no-op; different wording or a later stated_at creates a new event on the same subject.

4. Direct public action

Use one explicit host-neutral facade action:

review.py record-rationale --ticker <TICKER> --statement <TEXT> [--stated-at <DATE>]

The host normally hides the CLI and invokes it from natural language.

Route rules:

1. Resolve the ticker against the canonical recorded book under the write lock.
2. Exactly one active cycle → append.
3. No active position → append nothing. A live contemplated trade belongs to [feat·M2] DecisionIntent memory — automatically record a live trade intent, then resolve it from execution evidence or one follow-up #636; otherwise return a controlled holding-specific error.
4. Ambiguous active subject or changed book/state version → fail closed and retry; never attach words to a guessed cycle.
5. No card, Review Plan, commitment, rule choice or second save-confirmation.

5. Review and light-capture collection

A user answer to a rationale-refresh question is independently valid memory. The review invokes the same append service and records the returned event_id; it does not maintain a second session-owned rationale truth.

If the review later aborts, the rationale remains valid: the user explicitly stated why they hold the position, and that fact does not depend on the card finalizing.

The existing light capture UX may remain, but its writer delegates to this service. Any thesis projection it still needs is rebuilt or derived from the canonical event; direct appending to a rebuildable projection is retired.

Bounded reader contract (#450 handshake)

The first query is position-specific and bounded:

• earliest eligible event;
• latest eligible event;
• up to six most recent remaining events;
• total_count, shown_count, beyond_cap;
• effective current statement plus latest confirmation/change event;
• verbatim text, source/voice, stated_at, recorded_at, event id and subject identity.

The reader follows engine-proven cycle relinks/carry-forward aliases. It never joins by ticker alone across an unproven sale/rebuy boundary.

Review integration

Add a bounded rationale_refresh opportunity/question rather than turning every missing rationale into a questionnaire.

Eligibility requires an existing active rationale plus a fact that could make a new answer useful, for example:

• material new trade in the cycle;
• due/crossed condition or horizon;
• meaningful position change after a stale statement;
• behavior/self-report conflict evidence.

The engine supplies those facts and how long since the last statement. The agent chooses whether this question deserves the one available slot. At most one rationale-refresh question per review; the global route question budget is unchanged.

A no_change answer references the prior substantive event. A changed answer writes new exact wording. The question quotes the prior statement; it never asks as if nothing was recorded.

The first user-visible reader is the next review question/context. Do not add an unconditional card section in this slice.

Ordered implementation

Front A — stable subject continuity (#539 / #536)

Create one shared engine-side carry-forward/relink primitive used by both refresh-lane and review-lane snapshot adoption. A continuously held position preserves its cycle lineage; a confirmed sale and later re-entry opens a new one. Rationale queries consume the same relink chain. #563's later-history start-date upgrade must preserve aliases rather than orphan memory.

This front touches snapshot/ledger identity and has its own PR/review boundary.

Front B — canonical event and bounded query

In parallel with Front A, on disjoint files:

• schema;
• position_rationale module;
• append/idempotency/corruption tests;
• status/export/reset registration;
• [arch·M2] Canonical bounded execution-qualified self-report history #450 bounded query fixture.

No review.py integration yet.

Integration slice — direct entry + next-review reader

After Front A and Front B stabilize:

• add record-rationale through review.py;
• stamp/verify state_version;
• expose bounded current rationale in Review Plan state;
• add one rationale_refresh opportunity/question and duplicate-question suppression;
• prove direct entry changes the next review visibly.

This is the first owner-live stop boundary.

Follow-up slices, not in the first PR

1. Migrate the light capture and full-review capture paths to the same writer.
2. Optional condition mapping. Preserve any supplied invalidation wording first; do not claim monitoring until a canonical condition link exists.
3. Same-ticker consider reader after [QA·dogfood] Judgment-quality dogfood — does a real consider answer now carry a supported insight? #610. It must freeze the exact rationale event used and settle whether that reference participates in evaluation_id; do not slip it in as display-only mutable context.
4. Behavior/self-report verdict and profile consumption under [design·P1] The distillation layer: bounded profile memory over the append-only ledger (scoping) #446.

Acceptance criteria — first vertical slice

• An active position accepts one direct rationale without a Review Plan or card.
• Exact words round-trip byte-for-byte; first / changed / no-change semantics are distinct.
• Exact retry is a no-op; conflicting duplicates fail closed.
• No-position, ambiguous-position and stale-state cases append nothing.
• Direct, review and light routes have one canonical writer; no parallel theses.jsonl truth.
• The next review reads the event, quotes it when relevant and does not ask the same fact from zero.
• A continuously held snapshot position retains the memory across adoption; sold/rebought does not inherit it.
• The bounded reader reports truncation honestly.
• Status/export/reset cover the stream; corruption and interruption preserve prior canonical bytes.
• Review/card/TradeEvaluation arithmetic and current [QA·dogfood] Judgment-quality dogfood — does a real consider answer now carry a supported insight? #610 behavior remain unchanged.
• Public fixtures and evidence are fictional.

Non-goals

• No generic add-memory command or universal memory graph.
• No mandatory falsifier for every rationale.
• No automatic semantic drift/accusation.
• No price target, recommendation or execution claim.
• No consider integration in the first vertical slice.
• No profile label or standing-rule implementation.
• No migration that upgrades legacy classifications into user-verbatim statements.

Decisions still open

No owner decision blocks the first vertical slice above. The design deliberately resolves command shape, canonical source, first reader, snapshot-continuity prerequisite and first-statement semantics.

Later slices still require separate decisions/evidence:

1. whether an auto-loaded rationale reference changes TradeEvaluation.evaluation_id or remains a non-identity display context — decide before the consider consumer;
2. how a direct rationale and a direct condition append become atomically/recoverably linked without creating two canonical truths;
3. when repeated rationale/behavior mismatch earns a [design·P1] The distillation layer: bounded profile memory over the append-only ledger (scoping) #446 verdict rather than merely a question;
4. [design·P1] A rule is the user's own standing expectation, not a review output — the loop, and what currently forces it through one door #650's independent standing-rule lifecycle and adherence accumulation.

Dependencies / relations

• [arch·M2] Canonical bounded execution-qualified self-report history #450 — bounded self-report query contract; its first position-rationale slice may land before [feat·M2] Explicit execution link promotes an evaluation into durable decision memory #490.
• [bug·design·P2] Every new snapshot declaration re-asks for theses it was already given #539 / [bug·design·P2] A review-lane anchor adoption spends the user's holding-duration answer #536 / [design] A snapshot-inferred cycle start is now final — the relink that let a later CSV correct it rode on the completeness flag #549 removed #563 — subject continuity and relink safety.
• [feat·M2] DecisionIntent memory — automatically record a live trade intent, then resolve it from execution evidence or one follow-up #636 — no-position live intent.
• [feat·M2] Explicit execution link promotes an evaluation into durable decision memory #490 — execution truth, not a prerequisite for continuing-hold rationale.
• [design·P1] Two questions collect an answer nothing reads: initial_thesis and exit_consistency (proved by a byte-identical card) #429 / [process·gate-debt] Disposition tracker: 34 fields the deepened QUESTION_CONSUMERS field-level check found unread across 4 sinks #480 — writer-without-reader precedents.
• [design·P1] The distillation layer: bounded profile memory over the append-only ledger (scoping) #446 — later profile/verdict consumer.
• [design·P1] A rule is the user's own standing expectation, not a review output — the loop, and what currently forces it through one door #650 — sibling standing-memory object.
• [QA·dogfood] Judgment-quality dogfood — does a real consider answer now carry a supported insight? #610 — parallel frozen M1 dogfood, not a dependency.

Privacy / rollback

All real statements remain local under the user's coach root. Public tests/issues/receipts use fictional wording and instruments only.

Rollback before integration removes the new reader/writer without mutating ledger, sessions or TradeEvaluations. After events exist, rollback must leave the canonical stream exportable/readable even if no runtime surface consumes it; never delete user statements as part of code rollback.

[atomchung]

Owner ruling 2026-07-26: this issue holds two different user situations, and the ordering question was the wrong shape

1. Split the two situations. They are not one feature:

	asks	hangs off	cadence
(a) refreshing the holding rationale	"you still hold this — is the reason still the same?"	the position's continued existence	periodic
(b) trade motive	"why did you buy/sell this time?"	one trade	event-driven

Today initial_thesis implements only (b), and only on first_review. What this issue is mostly about is (a).

Only (a) can produce drift, which matters because drift is this issue's whole thesis. Drift needs a series of statements about the same position; (b) describes a different trade each time, so its answers are supposed to differ and their variation carries no signal.

Their triggers differ naturally too. (b) needs a new trade, and needs to be asked while the memory is fresh (the recency finding in #398). (a) needs no trade at all — a position you did not touch this quarter but which moved 60% is exactly when "is the reason still the same?" is worth asking.

2. The question-budget contention in "Open" above is not a rule to be decided. It was posed as "which wins on a given week, motive re-asks or the condition question". Owner:

對我來說應該有一個重要性的判斷 … 很難直接基於這一點來回答，它更多的是在當下那個場景中重要。

(There should be an importance judgment … this can't really be answered in the abstract; it matters within the specific situation at hand.)

Any static priority table is wrong in some situation. The split is:

• Engine supplies the facts: how far the position moved, whether there were new trades, whether a declared horizon passed, whether a stored condition came due, how long since the last motive statement for that position.
• Agent judges which question this week's slots are worth spending on, given those facts.
• What actually needs deciding is the budget (currently max 3/week), not the ordering.

This is the same engine/agent boundary the rest of this line has been converging on: the engine owns what is mechanically true, the agent owns relevance. Related: #412's judgment-cost ruling constrains how many of these can be surfaced at all.

[atomchung]

Owner ruling 2026-07-26: wire it, and the four fixed options are the wrong shape

Two rulings, recorded so this is not re-litigated:

進場動機要接到我們的決策啊，因為你進場動機就會是你下一輪的判斷依據啊，也會是你持續持有的依據啊,那肯定是要接入到消費者體驗裡面的。

Asking about entry motive is legitimate and stays. What is broken is (a) the answer reaches nothing today (#429), and (b) the options offered.

目前的問題，你給我的選項，我覺得有問題 […] 如果現在的反饋是關於問題太多的取捨問題，那我們需要在另一個報告中單獨討論。但從動機的角度來看，我覺得問這個問題沒有問題。我們可以探討動機，那麼我們的需求是，在有了動機之後，我們可以做些什麼。

Question density is explicitly out of scope here — that belongs with #291. This issue owns the consumer design.

What the four options throw away

planned_entry / momentum_follow / external_call / no_clear_thesis are a classification, not a reason that can be checked later. Two users who both answer planned_entry may be holding for "AI capex keeps growing" and "the CEO is a genius"; one of those is checkable next quarter and the other is not, and the enum erases the difference. It is the same defect #412 named in the observable catalog: a closed enum discards precisely the most informative thing the user can give — the reason our defaults did not anticipate.

The vehicle already shipped

#430 landed conditions.py and references/condition-slots.md for the commitment step. The same envelope is what a motive should be captured as:

• criterion — the user's own sentence, verbatim, never tidied into product phrasing
• query — a frozen neutral factual lookup, never the criterion restated as a yes/no question
• observation — the figure looked up in the same exchange and shown back ("it is 38% right now"), so a wrong basis exposes itself through the number and an unfindable quantity is known before the user walks away believing it is being watched
• verdicts met / near_line / not_met / unknown, and unmapped as a first-class honest state when nothing can be found

A motive stored this way stops being a label and becomes something that can be falsified — which is the whole point of asking.

What having the motive buys, in build order

1. The next review's holding basis (cheapest, and the wiring #429 is about). The motive goes into state_snapshot, and the next review opens by putting it back: "last time you recorded MSFT as a momentum entry." headline_motive already does exactly this — _headline_motive_history reads it back and it reaches the card. initial_thesis needs the same one line, nothing more.

2. Entry × exit consistency. The engine already scores early exits (exit_consistency, #303) and holding horizons (horizon_markers). Entry motive is the missing half of the pair: momentum-in / locked-the-gain-out is coherent, while "a three-year thesis" entered and then sold two days later on fear is the contradiction worth naming. Today both halves sit in isolated append-only logs, so they cannot be paired.

3. The series, and its drift — this issue's original core, owner-ruled 2026-07-25. Revenue growth → "it's a good company" → "I'm down too much to sell" is the diagnosis, and no single answer had to be accurate. This needs both halves: ask repeatedly (this issue) and have the answer read (#429). Fixing only this one collects more unread records.

4. Falsification against what actually happened. With a criterion plus a frozen query, the next review can report not_met on the reason the user gave — the strongest form of "what can we do with it", and the one that makes a motive worth collecting at all.

Order of work

#429's wiring is the precondition for all four: a motive that reaches nothing cannot be reconciled, paired, serialized, or falsified. Suggested cut, smallest first:

1. initial_thesis_events gets a history read-back and a state_snapshot slot (mirrors _headline_motive_history). Removes it from [design·P1] Two questions collect an answer nothing reads: initial_thesis and exit_consistency (proved by a byte-identical card) #429's KNOWN_UNWIRED ratchet and makes consumer 1 real.
2. Replace the closed option set with the condition-slot envelope for motives, unmapped when nothing is checkable ([feat·design·P1] The observable catalog is closed — user-meaningful conditions need slots, agent adjudication, and two-sided reasoning #412's standard).
3. Then the staleness/cadence rule this issue already specifies, so the series accumulates.

Guard already in place

evals/run_episodes.py's question-consumer gate (#429, merged in #431) fails the suite if a question kind ships with no verifiable consumer. When step 1 lands, initial_thesis must leave KNOWN_UNWIRED or the run says so — the ratchet only turns one way.

[atomchung]

Cross-link: the case where the user's reason cannot be falsified at all ("管理層很強", "AI 是長期趨勢") is now parked in #432 rather than folded in here. It matters to this issue's design because an unfalsifiable motive makes every later review report that the reason still holds — the product would read as validating a thesis that was never capable of being wrong.

So the condition-slot capture proposed above has a boundary: it works for a motive that names something observable, and for everything else unmapped (record the sentence verbatim, watch nothing, say so) is the honest floor until #432 is designed. Owner has deferred #432 deliberately — complexity is high and the follow-up ladder is exactly where the product could start manufacturing convictions the user did not have.

[atomchung]

Owner rulings, 2026-07-27, while scoping #446

Two rulings from the distillation-layer discussion land on this issue's territory.

1. A prior test for opening any question at all:

加不加這個欄位對於答案差異 問問題前基於這討論

Before a field earns a question, it has to change the answer. This generalizes the reasoning already recorded in this issue (importance is situational, budget is the agent's call) into a check that runs before the budget question is even reached.

2. Behavior is the ground truth; self-report is a second line, not the primary one:

一切以行為為主，如果行為和自述衝突，丟出來問用戶這是復盤重要體現

The mismatch between the two is where the review earns its value — but per the owner, that mismatch is a verdict, a separate object from either the self-report or the profile. See #446 for the three-way split.

3. The passive personality fields stay passive, for now:

現階段不主動問，這是後續討論點 但還不關鍵。長期可以有一個用戶自述的內容，該持續保存

source_type / emotion / confidence / driver keep their current best-effort capture — attached to questions that exist for other reasons, never asked for on their own. Whether they ever earn dedicated questions is explicitly deferred, and explicitly not urgent. The consequence to accept knowingly: thesis-policy.md documents these as unbackfillable, so coverage stays a function of what a conversation happens to touch.

What is not deferred is the second half of that ruling — a durable, long-lived record of what the user said in their own words. That is #450, since the gap there is a missing reader rather than a missing capture.

Refs #446, #450.