alphacouncil-agent 0.9.4 → 1.0.1

package/docs/plans/v1.1-basket-native-seats.md

@@ -0,0 +1,267 @@
+# v1.1 — Every seat can price a basket
+
+## The complaint, and what is actually wrong
+
+A SOX run ended with 25 of 27 seats `out_of_scope`. That reads as "the masters don't answer",
+and the reflex is to blame the seats. The seats are not the problem. Three separate things are.
+
+### 1. SOX has no data path at all
+
+`INDEX_PROXIES` covers `^GSPC`, `^NDX` and `^DJI`. `FUND_REGISTRY` covers eleven tickers.
+Neither contains `^SOX`, `SOXX`, `SMH` or `SOXQ`. With no registered holdings source there is no
+look-through, no top-ten weight, no breadth, no aggregate valuation — so even `master_bogle`,
+the seat built specifically to price a basket, had nothing to read and correctly abstained.
+
+The run reported this honestly ("缺少同日SOX聚合估值", "SOXQ 只是6月30日滞后代理"), which is
+why it is diagnosable at all. But an honest report of a gap is not a substitute for the data.
+
+### 2. A failed fetch silently halves the answer
+
+Two QQQ runs minutes apart, same code:
+
+| run | basket facts produced |
+|---|---|
+| A | 13 — top-ten weight, HHI, breadth ×2, AUM, leverage, revenue growth, aggregate P/E ×3, dividend yield, ERP, percentile |
+| B | 6 — the aggregate valuation block only |
+
+One failed holdings fetch removes everything downstream of it. Nothing in the report says the
+run was degraded, so the same symbol answers differently on different days and the difference
+looks like the seats changing their minds. **A degraded run must be labelled as degraded.**
+
+### 3. Company facts do not rise to the basket level
+
+This is the real one, and it is a design gap rather than a defect. On QQQ — where the data IS
+complete — 18 of 27 seats are still blocked, and the blocking facts fall into three classes:
+
+| class | facts | seats blocked |
+|---|---|---|
+| **Absolute currency** | `capital_allocation.share_count`, `financial.free_cash_flow_5y`, `financial.owner_earnings`, `financial.net_current_asset_value`, `valuation.downside_asset_value`, `valuation.downside_floor` | 10, 4, 2, 1, 1, 1 |
+| **Pure ratio, legal but unwired** | `accounting.cash_conversion`, `financial.gross_margin_5y`, `financial.net_margin_5y`, `financial.interest_coverage`, `financial.return_on_equity_10y`, `financial.incremental_return_on_capital` | 4, 2, 2, 2, 1, 1 |
+| **Index-level market data** | `options.implied_volatility`, `options.skew_25d`, `execution.bid_ask` | 5 |
+
+`capital_allocation.share_count` alone blocks ten seats — and no seat wants the share count.
+They want it as a **denominator**: owner earnings over market capitalisation, free cash flow
+over market capitalisation, net current assets over price. Summing share counts across a basket
+is meaningless, which is exactly why `LOOK_THROUGH_BLOCKED` refuses it. But converting each
+constituent's absolute figure to a **yield first**, then weighting the yields, is arithmetically
+sound and is what those methods were reaching for anyway. The existing code comment says so:
+
+> "…so they become yields first. That is real and worth doing; it is simply not this pass."
+
+This is that pass.
+
+## What this is not
+
+It is not "make the masters say something about indices". A seat that produces a number because
+the pipeline handed it one, without the number meaning what the method means, is worse than an
+abstention — it is an abstention wearing a verdict. Two rules govern every change below:
+
+1. **A basket reading must be the same question the method asks of a company.** Buffett asks
+   what the business earns for its owners against what the market charges. Asked of a basket
+   that is a weighted owner-earnings yield. Asked of a basket it is *not* "the ETF's owner
+   earnings", and no amount of wanting an answer makes it one.
+2. **A threshold authored for a company is not automatically valid for a basket.** Graham's
+   net-current-asset test on any broad index will fail every time; a seat that always says the
+   same thing regardless of input has no information in it. Where a company threshold is
+   degenerate on a basket, the seat gets an explicitly authored basket band — or it keeps
+   declining, and says why.
+
+## Plan
+
+### Phase A — coverage and honesty (immediate, fixes the reported run)
+
+**A1. Register the missing baskets.** `^SOX`, `^RUT`, `^IXIC` in `INDEX_PROXIES`; `SOXX`, `SMH`,
+`SOXQ`, `IWM`, `VTI`, `XLK`, `XLF`, `XLE` and the rest of the sector SPDRs in `FUND_REGISTRY`.
+Each needs a real issuer product id or slug, verified against a live fetch, not guessed.
+
+**A2. Fail loudly on an unregistered basket.** Today an unknown index quietly produces nothing.
+It should name itself as unregistered and say which issuer file would fix it, so the next SOX is
+a one-line registry addition rather than a diagnosis.
+
+**A3. Label a degraded run.** The instrument block records which sources answered and which did
+not, and the report states it. A run that lost its holdings feed must not present as a run that
+had one. This is the difference between "the seats abstained" and "the data did not arrive".
+
+### Phase B — wire the ratio aggregates that are already legal (unlocks ~8 seats)
+
+`LOOK_THROUGH_FACT_RULES` maps two facts today. Every pure ratio in the table above aggregates
+as a weight-weighted mean under the same coverage floor already enforced (refuse below 50%).
+Add: cash conversion, gross margin, net margin, interest coverage, ten-year ROE, incremental
+return on capital.
+
+Unblocks munger, fisher, li_lu, forensic_short, taleb, soros, jhunjhunwala, bogle.
+
+**Done and measured.** Two things had to be fixed beyond the mapping itself:
+
+- The margins, cash conversion, ten-year ROE and interest coverage come from the **mechanical
+  screen**, not from the derived fundamentals — and the look-through only ran the latter, so
+  those aggregates could never have had inputs. Both readers now run on one Company Facts
+  document per constituent, at no extra network cost.
+- An aggregate arrived as a bare `decimal` with the outer envelope of its constituents'
+  reporting periods. Interest coverage and cash conversion are `multiple`s, and the union of
+  forty five-year spans is five years plus a year of calendar edges — so facts were present and
+  rejected by the contract, which reads exactly like being absent. An aggregate now carries the
+  same unit as its single-company counterpart, over the **median** constituent span.
+
+Result on QQQ: 13 basket facts → 18; blocked seats 18 → 11. The residue is almost entirely the
+absolute-currency class, which is what Phase C exists for — the control group the sequencing
+note asked for.
+
+### Phase C — per-constituent yields (unlocks ~10 seats, the big one)
+
+New aggregation kind in `funds.mjs`: `yield_of(absolute_fact, market_capitalisation)`. For each
+resolved constituent, divide the absolute figure by that constituent's own market cap, then
+weight the resulting yields. Produces:
+
+| new basket fact | from | unblocks |
+|---|---|---|
+| `valuation.owner_earnings_yield` | owner earnings ÷ mcap | buffett, ackman |
+| `valuation.free_cash_flow_yield` | 5y FCF ÷ mcap | graham, aschenbrenner, cathie_wood, lynch |
+| `valuation.ncav_to_price` | NCAV ÷ mcap | burry |
+| `valuation.downside_floor_ratio` | downside floor ÷ mcap | klarman, pabrai |
+
+Each seat's tool then reads the basket yield where it read a company yield. The arithmetic is
+identical; only the input changes. Market capitalisation per constituent is already available —
+the fundamentals path produces share count, and the quote path produces price.
+
+**Done and measured — and implemented differently from the sketch above, for the better.**
+Emitting new yield fact ids would have required re-authoring ten seats to read them. It is
+also not what a fund owns. A fund holding 1% of a company has a claim on 1% of its owner
+earnings, and summing that across the basket is a dollar figure ABOUT THE FUND:
+
+    fund's claim = AUM x SUM over i of ( weight_i / market_cap_i ) x figure_i
+
+This is ordinary look-through accounting, not the category error `LOOK_THROUGH_BLOCKED`
+refuses — that one sums constituents as though the fund owned each outright. Because a fund's
+market capitalisation IS its AUM, a seat dividing this claim by market capitalisation gets the
+weighted look-through yield **with no change to its method at all**.
+
+Per-constituent market capitalisation costs nothing extra: the share count is already fetched
+by the fundamentals pass and the price by the breadth pass, which fetched a year of closes for
+every constituent and threw the last one away.
+
+Two contract corrections fell out of it:
+
+- A share count is a point-in-time quantity, not a span. It was declared over a fiscal year
+  because that is how the filing reports it, which meant a fund's count — a genuine instant —
+  could satisfy no contract. It exists to denominate a market capitalisation, where how many
+  shares there are matters and which window they were averaged over does not; the averaging
+  basis stays stated in `assumptions`.
+- A claim inherits the reporting window of the figure it is a claim on.
+
+**The honest limit, recorded on every such fact:** a weighted mean of yields is not the yield of
+the aggregate, and the difference grows with dispersion. It is the right number for "what does
+the average dollar in this basket earn", which is the question these methods ask, and it is the
+wrong number for "what would this basket earn if it were one company". The fact carries which
+one it is.
+
+### Phase D — the basket's own option surface (unlocks ~4 seats)
+
+Volatility seats read `options.implied_volatility`, `options.skew_25d` and `execution.bid_ask`,
+none of which the basket path supplies today. Index options (SPX, NDX, SOX) and liquid ETF
+options both exist on the same chain endpoint the single-stock path already uses; the work is
+routing a basket symbol to its own chain rather than skipping options for non-companies.
+
+Unblocks simons, thorp, natenberg, sinclair; strengthens taleb.
+
+### Phase F — fund flow, which is currently a gap for every issuer
+
+Flow is the question people actually ask of an ETF — is money going in or out — and today the
+answer is "gap" for all four issuers, for two different reasons.
+
+`fundFlow` computes the only honest version: `(shares_now − shares_prior) × NAV`. Shares
+created and redeemed are what a flow IS; an AUM change is a flow plus a market move, and
+reporting the second as the first is the standard way this number gets faked.
+
+What is available, verified by live fetch:
+
+| issuer | shares outstanding | flow today |
+|---|---|---|
+| iShares | **yes** — in the holdings CSV header (`Shares Outstanding, "82,650,000.00"`) with its own date | no: only today's file is retrievable |
+| SSGA | sometimes — absent from some funds' holdings files | no |
+| Invesco | no — `/nav` and `/profile` both answer HTTP 501 | no |
+| Vanguard | no keyless endpoint | no |
+
+So even where the share count is published, only **one** dated observation is reachable, and a
+flow needs two. iShares serves no dated holdings file (`?asOfDate=` is a 404) and its product
+page carries field metadata, not a time series. There is no keyless history to fetch.
+
+**F1. An observation ledger.** Every run already retrieves the holdings file. Record what it
+saw — symbol, as-of date, shares outstanding, NAV, AUM — under the run data directory, append
+only, one row per symbol per as-of date. From the second observation of a symbol onward the
+flow is computable exactly, by the arithmetic already implemented.
+
+This bootstraps rather than backfills, and that is the honest trade: a user who runs SOXX
+weekly has weekly flows after the second week. It is not a substitute for a vendor flow series
+and the fact says so.
+
+**F2. Flow as a typed fact.** `fund.net_flow` (monetary, currency + scale) and
+`fund.net_flow_ratio` (flow ÷ AUM, so a small fund's move is comparable to a large one), each
+carrying the two dated observations it was computed from and the gap in days between them. A
+flow computed across a 40-day gap is not a daily flow and must not be read as one.
+
+**F3. Seats that should read it.** Flow is a crowding and reflexivity signal, not a valuation
+one. `master_soros` reads it directly — participant behaviour reinforcing price is his
+mechanism, and creations against a rising price is that loop in its most literal form.
+`master_druckenmiller` reads it as price confirmation. `master_marks` reads persistent inflow
+into an already-expensive basket as where the cycle stands. No valuation seat should read it:
+a flow says nothing about what a business earns.
+
+**Done and measured.** The accuracy question turned out to be the whole problem, and the
+answer is which share count is allowed to price a flow.
+
+A flow is a DIFFERENCE of two counts, so it cancels the number and keeps the error. Three
+routes to a count exist and only two may be differenced:
+
+| route | basis | flow-eligible |
+|---|---|---|
+| the holdings file's own `Shares Outstanding` (iShares) | filed | **yes** |
+| issuer assets ÷ issuer NAV, same source, same date | an identity, not an estimate | **yes** |
+| disclosed positions ÷ market price | reconstruction | **no** |
+
+The third is fine for a market capitalisation — the product is the size we already had — and
+unfit for a flow: a 95%-priced position sum and a premium to NAV each carry error that survives
+the subtraction. Half a percent at each end of a $300bn fund manufactures $1.5bn of flow that
+never happened, and it appears as conviction exactly when the market moved.
+
+The second route is what makes **sector ETFs** work, which is the case people ask about most.
+The Select Sector SPDRs publish no share count in their holdings file, but do publish assets
+and NAV — and assets over NAV is shares outstanding by definition. Verified live: XLK 654.8M
+shares, SOXX 82.7M from its filed count.
+
+**F4. Refuse rather than estimate.** Where only one observation exists, or the issuer publishes
+no share count at all, the fact is absent with a named reason. The failure mode this guards
+against is deriving flow from an AUM change — which would silently report a market rally as an
+inflow, and would be wrong in exactly the direction that makes a momentum story look confirmed.
+
+### Phase E — basket bands where the company threshold is degenerate
+
+For each seat unblocked above, decide explicitly whether the authored threshold means the same
+thing on a basket. Graham's NCAV line and Burry's net-net test are the obvious candidates for a
+basket-specific band. This is authoring work, per seat, and it is what stops Phase C from
+producing eighteen confident numbers that all mean "the pipeline handed me a float".
+
+## Expected result
+
+| | before | after A+B | after C |
+|---|---|---|---|
+| QQQ | 11/27 | 12/27 | **16/27** |
+| SOXX | 0/27 (unregistered) | 9/27 | **17/27** |
+| SOX | 0/27 (unregistered) | 1/27 | 1/27 |
+| AAPL (company path, control) | 18/27 | 18/27 | **18/27** |
+| union over seven symbols | 26/27 | — | **27/27, none mute** |
+
+QQQ trails SOXX because Invesco publishes no share count, so its market capitalisation is
+reconstructed rather than filed, and because more of its constituents fall below the
+look-through coverage floor. SOX itself stays low: it is a cash index with no aggregate P/E
+published by any implemented source, so the valuation seats have nothing to read even now.
+
+Measured the same way as v1.0.0: live grounding, no fixtures, contract failures counted
+separately from abstentions.
+
+## Sequencing note
+
+A and B are mechanical and independently verifiable. C is where the judgment is, and it should
+not start until B is measured — if wiring the legal ratios moves QQQ from 11 to 19, that is the
+control group that tells us the yield conversion is doing what it claims rather than the
+coverage improving underneath it.

package/docs/releases/v0.9.5.md

@@ -0,0 +1,96 @@
+# AlphaCouncil Agent v0.9.5 — ETF/Index Routing and Complete Method Handoff (Non-GA)
+
+`v0.9.5` is a non-GA GitHub preview that fixes the QQQ acceptance defects found after the
+`v0.9.4` locale release. It does not publish npm, change npm dist-tags, promote a PersonaPack
+maturity level, or claim a new investment conclusion for QQQ.
+
+This is a runtime/reporting release, not a method-pack revision. The build profile therefore
+pins `persona_pack_version=0.9.4`: all 26 reviewed solo-test pack hashes and their existing
+machine-simulation evidence remain unchanged while the package/plugin version moves to
+`0.9.5`. Runtime version bumps must not manufacture pack-hash drift and then rerun research
+merely to recover a green check.
+
+## Why 0.9.5 exists
+
+The failed QQQ experience exposed four separate defects:
+
+1. Yahoo's chart response identified QQQ as an ETF, but the quote adapter discarded
+   `instrumentType`. Grounding then used the operating-company path and could report the
+   predictable SEC Company Facts 404 as a research failure.
+2. Deterministic v3 methods correctly returned `out_of_scope` when their typed facts were
+   absent, but the visible handoff did not turn every abstention into a readable per-seat
+   statement.
+3. The PM completion path wrote `user_response.md`, then returned only a compact ACK to the
+   host. A host could therefore answer with a short recap and hide the selected-seat output
+   that existed in artifacts.
+4. `report_quality` required a Master Bench section but did not prove that every selected
+   stable method ID and readable final statement appeared in that section.
+
+These were runtime and delivery defects, not evidence that twenty-five methods were bearish.
+
+## Instrument routing
+
+- Quote parsing now preserves Yahoo `instrumentType`, names and exchange timezone.
+- A deterministic classifier distinguishes operating companies, ETFs, mutual funds, cash
+  indices, futures, FX and crypto. Yahoo metadata is primary; symbol conventions, quote names
+  and SEC ticker/registrant names provide bounded fallbacks.
+- The SEC ticker title and filer profile are resolved before Company Facts is scheduled.
+  ETF/fund/index routes explicitly mark operating-company Company Facts and structured issuer
+  financials as not applicable instead of recording a false failure.
+- ETF/fund runs use `fund_lookthrough`; cash indices use `index_aggregate`; operating companies
+  retain `operating_company`. The type, model and classification source are persisted in
+  `status.json`, grounding output and the research dashboard.
+- All eight evidence roles receive a role-specific fund/index assignment. The contract covers
+  dated holdings or constituents and weights, concentration, methodology, fees or index rules,
+  liquidity, premium/discount or tracking difference, flows, rebalances, lending/derivatives,
+  look-through earnings and same-date aggregate valuation with explicit coverage weight.
+- Fund/index prompts forbid fund revenue, company EPS, management guidance and fund-insider
+  Form 4 fabrication. A few constituent financial statements may never be added into a
+  portfolio financial statement.
+
+The classifier does not invent holdings, flows, aggregate EPS or valuation. Those remain
+dated evidence requirements, and missing fields remain report gaps.
+
+## Complete selected-seat handoff
+
+- Every deterministically completed or declined physical v3 seat now has a readable fallback
+  statement in the run language. An ETF/index abstention explains that the method needs dated
+  holdings look-through or aggregate-index evidence and that `out_of_scope` is not a bearish
+  vote.
+- `plan_visible_run` returns one explanation worker for every non-blocked selected physical
+  v3 seat, including a deterministically declined seat. The worker receives the finished
+  evidence, acknowledges the frozen stance, and may improve the explanation but cannot vote
+  again. PM completion checks `master_status`, not merely the presence of a fallback record.
+- The full chat handoff ends with the exact selected-seat count and one statement for every
+  selected stable ID. A full `all` selection therefore ends with 26 lines; quick mode reports
+  its actual 1–4 seats rather than claiming 26.
+- Labels state that these are project-derived provisional method-seat outputs, not quotations,
+  endorsements or current statements from the named people.
+- Visible PM completion returns `handoff_contract=inline_user_response_v1` and the saved
+  `user_response_markdown`. Host instructions require that body to be delivered instead of
+  replacing it with a shorter recap. Idempotent PM replays return the same handoff.
+- The final report owns an idempotent fund/index structure section and the recorded Master
+  Bench. PM narrative is retained as non-authoritative commentary where it conflicts with a
+  system-owned section.
+
+## Quality gates and regression coverage
+
+- `report_quality.json` records selected/readable/rendered method-statement counts and stable
+  IDs. Missing opinions, statements shorter than the readability floor, or an ID absent from
+  the published Master Bench force `needs_revision`.
+- Fund/index reports require the structure/look-through section; ordinary-equity reports do
+  not.
+- Offline unit and integration coverage includes QQQ/SPY ETF classification, SEC-name fallback,
+  cash-index routing, all eight ETF role overrides, fund/index report assembly, a 26-seat final
+  handoff, inline visible-PM handoff and replay, and unchanged equity behavior.
+
+## Assurance boundary
+
+- Build channel: `solo_test`.
+- Runtime/package version: `0.9.5`; unchanged PersonaPack snapshot: `0.9.4`.
+- Physical provisional packs: 26.
+- Persona tools: 52 `provisional_derived_proxy` tools.
+- Operational seats: 0.
+- Validated `method_model` seats: 0.
+- `production_eligible=false`; `method_model_eligible=false`.
+- Formal production GA remains fail-closed.

package/docs/releases/v1.0.0.md

@@ -0,0 +1,164 @@
+# AlphaCouncil Agent v1.0.0 — Seats That Can Answer
+
+`1.0.0` is the release where the method seats stop abstaining on everything.
+
+> **Status: released.** All twenty-seven seats are authored, the trees regenerate from committed
+> sources alone, and `npm test` is green at 961 tests. Measured against live grounding across
+> eight symbols, every one of the twenty-seven seats reaches a stance somewhere, with no
+> contract failures anywhere.
+
+## What was actually wrong
+
+A council of twenty-six method seats produced one usable opinion, and only on a narrow class
+of symbol. The QQQ run that prompted this release ended with twenty-five `out_of_scope`
+statements and one cautious note about implied volatility. That looked like an ETF problem.
+It was not.
+
+Three layers were empty, and each one hid the next:
+
+1. **Facts.** `grounding-adapter.mjs` is the only thing in the repo that produces typed facts,
+   and it could produce thirteen fact ids. Twenty-five seats required facts that nothing
+   generated. The same run against an operating company abstained identically — QQQ was not a
+   special case.
+2. **Method.** All twenty-six decision policies were the same generated template: empty
+   eligibility, empty vetoes, and two rules scoring an `identity` transform against zero.
+   Supplying the missing facts would have bought "owner earnings are positive, therefore
+   cautious" — true, and empty.
+3. **Expression.** An abstention rendered as `no_required_fact_types_present`, which reads as
+   a broken system rather than as a method declining.
+
+## Facts
+
+Four feeds, all keyless, each one refusing rather than approximating when a source is absent.
+
+**Dated official series.** The macro block already fetched rates, credit and breadth but had
+no publication date of its own, so the adapter skipped the family entirely. A point snapshot
+could not have fixed the seats that needed it: an impulse and a regime are directions, and a
+direction computed from one day of quotes is fabricated precision. FRED's CSV endpoint is
+keyless where its API is not, and every observation publishes its own date — which gives net
+liquidity, its change over a stated window, and the growth/inflation quadrant, each returning
+null rather than a guess when an axis lacks the history to have a direction.
+
+**Company fundamentals.** Owner earnings, NCAV, downside asset value and floor, revenue
+growth, incremental return on capital, leverage, share count — derived from XBRL with the
+filing date as `public_at`, never the clock. Owner earnings is labelled `estimated` rather than
+`rederived`: the maintenance/growth capex split is an assumption, and the proxy travels with
+the fact rather than living in a comment.
+
+**Fund holdings.** Four issuers' published daily files. Each has a trap that produces wrong
+data rather than an error, so each is checked: the retired iShares path returns HTTP 200 with
+an HTML body for every user agent, so the first line is validated instead of the status; the
+Invesco endpoint truncates to ten holdings under one parameter while still reporting the full
+count, so the count is the checked invariant; a guessed CUSIP resolves to a different fund
+entirely, so only verified identifiers are registered.
+
+**Index aggregates.** Valuation, breadth, put/call and volatility. Index P/E is quoted on
+incompatible bases — three sources disagreed by 4.6 turns on the same day — so every valuation
+fact names its basis and sources are never blended for one metric. Constituent lists are
+licensed assets, so constituents come from the tracking fund's published holdings, labelled a
+proxy in the provenance rather than presented as the index.
+
+**Look-through.** A basket has no income statement, which is why an operating-company method
+had nothing to read. Buffett defined look-through earnings in the 1990 shareholder letter for
+exactly this situation, so aggregating constituent ratios by weight is the method's own
+answer rather than a workaround. It stays honest by refusing: absolute-currency facts have no
+aggregation path at all — "the fund's owner earnings" is unrepresentable, not discouraged —
+and every aggregate carries the weight it was computed over, because a portfolio ratio
+measured across 8% of a basket is a different claim from one measured across 95%.
+
+## Method
+
+A seat may now carry its real formula and its real decision policy instead of the generated
+identity proxy. Authored inputs may only reference facts the build spec already declares, so
+the authoring layer cannot quietly widen a seat's contract.
+
+One distinction matters more than it looks: `min_coverage` is 1, so a single uncomputable
+*scoring* rule collapses an entire seat to `out_of_scope`. That is the mechanism that produced
+twenty-five abstentions. A "can this method speak at all" test belongs in eligibility, which
+has its own exit and its own explanation, and authored policies are written that way.
+
+**Assurance is unchanged and still fail-closed.** These formulas are AI-authored and unreviewed.
+An authored tool records `ai_authored_candidate_formula_not_human_reviewed` in place of the
+`mechanical_identity_proxy` claim, which would otherwise be false. Admission stays
+`operator_lens`, `production_eligible` stays false, and no human has reviewed either kind.
+
+## Expression
+
+Seats answer five questions in the first person — what I see, how my standard reads it, would
+I act, what changes my mind, where I disagree — and carry a `position_intent`. Intent narrows
+the frozen stance and never reopens it: each stance admits only intents meaning the same thing,
+enforced server-side exactly as a changed stance is, so a worker cannot turn `opposed` into
+`would_buy` by choosing a label.
+
+First person is what makes the output readable and is also exactly what could be mistaken for a
+quotation. The prompt requires the method's voice — "this standard asks for X" — never a claim
+about what a living person currently thinks, and the section says so.
+
+The bench separates seats that reached a decision from seats that could not. The old layout
+gave both equal weight, so a run where twenty-five seats abstained printed twenty-five
+near-identical rows and buried the one seat with a view. Abstentions now collapse into a single
+paragraph that still names every stable ID — both what the publication gate checks and the
+honest requirement that no seat quietly vanishes.
+
+## Fixed
+
+- The classifier failed open. With no exchange metadata — the fallback quote path, which
+  returns a null instrument type — common fund tickers matched a bare ticker shape and were
+  asserted to be operating companies, reproducing the exact defect 0.9.5 set out to fix. A
+  filed SIC was documented as evidence of an operating company, but the codes in question are
+  what fund registrants file. A fund named after an index matched the bare `index` token and
+  was routed as a cash index, which silently disabled its option chain.
+- Reports in Japanese and Korean could never publish. A relabelled commentary section legally
+  contains a section alias, heading assignment keeps the richest body, and the per-seat gate
+  then failed against PM prose — permanently, since more prose only made the commentary win
+  harder. The gate now locates the system section by its content anchor.
+- Worker statements were interpolated raw into a system-owned section, so a statement
+  containing a heading captured the section the quality gate validates.
+- The status snapshot and the blocking gates disagreed about a seat with no status entry, so a
+  recovered run reported complete while being hard-rejected.
+- Declined seats no longer schedule an explanation worker. The stance is frozen and the
+  deterministic record is already readable, so the worker could change nothing while costing
+  one sequential model turn per seat on a host with no fan-out.
+- The fundamentals path re-registered filing records under the consuming metric's period,
+  which silently dropped every fact sharing a record with the mechanical screen.
+- The look-through aggregator reads one number per ticker and was handed a nested object, so
+  every aggregate reported "no constituent supplied this metric" while the constituents sat
+  resolved in memory.
+- `not_applicable` strings and the fund/index research contract were English-only inside
+  localized reports.
+
+- The typed-fact period contract was wrong in three ways at once, and together they were why a
+  live run stayed near-silent even after the facts and the methods were in place. The adapter
+  stamped an observation date into `period_end` with no start, a shape that satisfies no
+  contract basis at all — rejected as an instant because the interval is non-null, and as a
+  duration because a window needs both ends — so those facts were unusable by any tool.
+  Multi-year aggregates were declared as instants, which the executor rejects against a fact
+  that carries a reporting interval. And the one-year window demanded 365 days, while a fiscal
+  year measured between two year-end dates is routinely 363. Facts that cover a span now
+  declare a duration; coverage set by filing availability rather than by the method declares
+  `ANY`; and look-through aggregates carry the interval their constituents reported. Measured
+  across eight symbols before and after: from four seats reaching a stance to twenty-six, with
+  no contract failures left.
+- Every seat-count and tool-count invariant is derived from the canonical roster instead of
+  restated as a literal. Adding the twenty-seventh seat previously meant editing sixty
+  assertions across tests, schemas and reports, which is the kind of cost that keeps a bench
+  frozen at whatever size it was first written at.
+- The twenty-seventh seat could not speak on this universe at all. `master_jhunjhunwala` puts
+  the ownership record first, before any growth arithmetic, and the US has no promoter as a
+  filing concept — so the seat was authored to decline by construction, which is honest and
+  also useless. Section 16 is the filed analogue: officers, directors and holders of more than
+  ten percent file Forms 3, 4 and 5 stating what they hold afterwards.
+  `governance.insider_ownership` sums the newest such filing per reporting owner over shares
+  outstanding, reading filings newest-first and taking each owner once, so the cost is one
+  fetch per insider rather than one per filing. The fact is `estimated`, not `reported` — no
+  document states it — and where Section 16 differs from an Indian promoter disclosure is
+  written on the seat rather than adjusted away.
+
+## Assurance boundary
+
+Unchanged from 0.9.5 and deliberately so:
+
+- Build channel: `solo_test`; `production_eligible=false`; `method_model_eligible=false`.
+- Admission level: `operator_lens`. Formal production GA remains fail-closed.
+- Method-seat outputs are project-derived provisional lenses. They are not quotations,
+  endorsements, or current views of the named people.

package/docs/report-contract.md

@@ -22,6 +22,13 @@ writes the mode-appropriate versions of:
 The report and handoff must call a named master result a recorded method-seat or lens result.
 It is not a quote from, endorsement by, or current statement of the named person.
 
+The run classifies its instrument before selecting financial-data routes. Operating-company
+Company Facts and issuer financials are not applicable to ETFs, funds or indices. ETF/fund
+runs use holdings look-through; index runs use aggregate-index evidence. Missing dated
+holdings, constituents, weights, methodology, fees/rules, liquidity/tracking/flows or
+aggregate-valuation coverage remain explicit gaps and are never replaced with invented fund
+revenue, EPS, guidance, insider activity or summed constituent financial statements.
+
 System-owned selector, report and handoff labels are localized for `zh-CN`, `en`, `ja` and
 `ko`. Each worker receives the canonical run language, while stable IDs and JSON field names
 remain English. Reader-facing evidence, method, debate and PM fields are checked against the
@@ -40,6 +47,7 @@ Full remains the default. Its `final_report.md` visibly covers:
 - analyst work log for every planned evidence role
 - bull/bear debate record, including three rounds and exact round-3 Q&A
 - recorded Master Bench when methods were selected
+- fund/index structure and look-through when the instrument is an ETF, fund or index
 - long thesis and short thesis
 - market expectations and implied beat/miss thresholds
 - analyst rating and target-price revisions
@@ -62,10 +70,17 @@ Its `user_response.md` must also visibly carry:
 
 - a system-owned price snapshot with price, currency, quote timestamp, exchange/feed and
   source when available, or an explicit statement that the quote is unavailable;
-- every selected stable master ID, its frozen deterministic stance, its isolated voice-worker
+- every selected stable master ID, its frozen deterministic stance, its readable
   explanation/status and a clear `not a quote` attribution boundary;
 - all eight mandatory analyst task IDs, statuses and summaries, including failures or gaps;
 - terminal status, contract, report quality, elapsed time, deadline state and artifact paths.
+- a final section with the exact selected-seat count and one readable statement per selected
+  stable ID. Full `all` therefore ends with 26 statements; quick reports its actual 1–4.
+
+Visible PM completion returns `handoff_contract=inline_user_response_v1` plus the persisted
+`user_response_markdown`. The host uses that body for the final reply instead of reducing it
+to a compact ACK and hiding the method-seat tail. An idempotent PM replay returns the same
+handoff.
 
 All mandatory full evidence roles must be completed. If one still fails after the one bounded
 parse-only repair, full fails closed at the evidence barrier: no master, bull/bear or PM model
@@ -95,8 +110,11 @@ those subagents and the plugin cannot force-stop them.
 Visible full runs use the same six role-by-round audit records and exact Q&A gate. Each
 Bull/Bear call declares round 1, 2 or 3; the server rejects out-of-order calls, altered replay
 content and a PM submitted before both Round-3 records pass. Identical role/round retries are
-idempotent. This preserves workflow completeness but does not give host-owned subagents the
-plugin-managed 30-minute deadline.
+idempotent. Every non-blocked selected physical v3 seat also returns a visible post-evidence
+explanation worker, including a deterministic `out_of_scope` seat. Its
+`acknowledged_stance` must match the frozen stance, and PM checks the worker's completed
+status rather than accepting the fallback record alone. This preserves workflow completeness
+but does not give host-owned subagents the plugin-managed 30-minute deadline.
 
 ## quick_v1 Contract
 
@@ -201,7 +219,7 @@ one judgment paragraph, valuation/position, material gaps and file locations.
 A full handoff additionally carries the key earnings result, forward setup, news/voice
 signals and top invalidation conditions. It lists every selected method seat and all eight
 mandatory analysts rather than sampling a subset, and includes the system-owned price
-snapshot or an explicit quote-data gap.
+snapshot or an explicit quote-data gap. The method-seat list is the final handoff section.
 
 A quick handoff instead names:
 
@@ -227,7 +245,9 @@ Both handoffs list `final_report.md`, `artifact_index.md`, `all_agents.md`, and
 | "The source table mentions the news, so the news section can be skipped." | News findings need their own visible section; quick recent news must also pass its date window. |
 | "The final report exists, so chat can hide file locations." | The handoff lists the saved report, index, trace and quality file. |
 | "The master said this." | Call it a recorded method-seat result, never a quote from the named person. |
-| "The full report has a bench table, so the handoff can hide the individual seats." | Full handoff lists every selected stable ID, stance and isolated-worker result/status. |
+| "The full report has a bench table, so the handoff can hide the individual seats." | Full handoff ends with every selected stable ID, stance and readable result/status. |
+| "The PM tool returned success, so its small ACK is enough." | Deliver `user_response_markdown`; success metadata is not the user-facing report. |
+| "QQQ has a ticker and SEC CIK, so run the company screen." | Classify first. ETF/fund/index company financial routes are not applicable; use look-through or aggregate evidence. |
 
 ## How the Quality Gate Checks Reports
 
@@ -246,4 +266,8 @@ at least 1600 non-space characters, quick reports 700, and dry reports 600.
 
 The system-owned recorded Master Bench and degraded ledger are checked independently of PM
 prose so a generic, stale or duplicate heading cannot satisfy the contract. The authoritative
-lists are `REPORT_SECTIONS` and `QUICK_REPORT_SECTIONS` in `mcp/lib/constants.mjs`.
+Master Bench must contain the exact stable ID and a readable statement for every selected
+seat; `report_quality.json.method_statement_coverage` records selected/readable/rendered
+counts and IDs. A missing statement or ID forces `needs_revision`. Fund/index runs also
+require the system-owned instrument-structure section. The authoritative lists are
+`REPORT_SECTIONS` and `QUICK_REPORT_SECTIONS` in `mcp/lib/constants.mjs`.