alphacouncil-agent 1.0.0 → 1.0.1

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "AlphaCouncil plugins for public-equity research.",
-    "version": "1.0.0"
+    "version": "1.0.1"
   },
   "plugins": [
     {
       "name": "alphacouncil-agent",
       "source": "./",
       "description": "Multi-agent company, ETF and index research: evidence packets, method seats, bull/bear debate and portfolio-manager synthesis.",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "author": {
         "name": "Zhao73"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "alphacouncil-agent",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Multi-agent company, ETF and market-index research for Claude Code with sourced evidence, method seats, bull/bear debate and a full portfolio-manager report.",
   "author": {
     "name": "Zhao73"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "alphacouncil-agent",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Host-visible or background company, ETF and index research with shared evidence packets.",
   "author": {
     "name": "Zhao73"

package/AGENTS.md

@@ -10,12 +10,11 @@ Run `npm run check` after any code or prompt change.
 
 ## Current Release Boundary
 
-Package/plugin version `1.0.0` is a non-GA GitHub preview. This source upgrade does
-not mutate npm dist-tags; verify npm independently before claiming `next` serves 1.0.0. Its
-build channel remains `solo_test`: 26 physical provisional
-PersonaPack v3 packs, 26 `operator_lens` seats, 52 `provisional_derived_proxy` tools,
-0 operational seats and 0 validated `method_model` seats. Do not present this feature
-release, a passing full/quick report or a packaged smoke as PersonaPack production GA.
+Package/plugin version `1.0.0` is the published default install. It carries 27 physical
+PersonaPack v3 packs, 27 `operator_lens` seats and 54 executable tools, with 0 validated
+`method_model` seats. Human review of the authored formulas and the live four-host
+end-to-end run are outstanding, so do not present a passing full/quick report or a packaged
+smoke as evidence that either has been done.
 
 ## Council Modes
 

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 Notable changes per release. Dates are UTC.
 
+## [1.0.1] — 2026-07-29
+
+A SOX run ended with 25 of 27 seats abstaining. The seats were not the problem.
+
+### Fixed
+
+- **A basket nobody registered produced no facts.** `^SOX` was not in `INDEX_PROXIES` and
+  `SOXX` was not in `FUND_REGISTRY`, so there were no holdings, no look-through and no
+  aggregate valuation — and `master_bogle`, the seat built to price a basket, abstained with
+  the rest. `^SOX` and `^RUT` are mapped, and 25 more baskets are registered, every product id
+  read from the issuer's own screener and verified by live fetch.
+- **An index typed without its caret did not route to the index path.** `^SOX` classified as an
+  index and `SOX` did not, so a run on the name people actually type produced nothing.
+- **`funds.mjs` re-exported six parsers it also calls.** A bare `export ... from` publishes a
+  name without binding it, so every live fetch path threw `not defined` while the parser tests,
+  which import directly, stayed green.
+- **Three recorded data gaps were closed and still being reported** — breadth, the implied ERP
+  and the valuation percentile. A note about a fact the pack produced reads as a gap that is
+  filled, which sends a reader to solve a solved problem.
+
+### Added
+
+- **Company methods can price a basket, without changing their methods.** A fund holding 1% of
+  a company has a claim on 1% of its owner earnings; summed across the basket that is a dollar
+  figure about the fund, and a fund's market capitalisation is its AUM, so a seat dividing one
+  by the other gets the weighted look-through yield. Ten seats were blocked on a share count
+  and none of them wanted a share count — they wanted a denominator.
+- **Every pure ratio a constituent reports now aggregates**: cash conversion, both margins,
+  ten-year ROE, incremental return on capital, interest coverage. Coverage aggregates
+  harmonically, because one debt-free constituent at 900x drags an arithmetic mean to
+  "comfortably covered" for a basket that is not.
+- **ETF flow**, from an append-only ledger of what each run saw, because no issuer serves a
+  keyless share-count history. Only a filed count or the issuer's own assets-over-NAV identity
+  may price a flow; a count reconstructed from positions over market price may size a fund and
+  is refused for a flow, because a difference cancels the number and keeps the error. Eleven
+  Select Sector SPDRs registered, which is where the question is usually asked.
+- **A cash index reads its tracking ETF's option chain**, labelled a proxy, the same discipline
+  the holdings path already applies.
+
+### Changed
+
+- A share count is carried as a point-in-time quantity. It was declared over a fiscal year
+  because that is how the filing reports it, which left a fund's count — a genuine instant —
+  unable to satisfy any contract.
+
+Measured on live grounding: SOX 0 seats to 6, SOXX 0 to 17, QQQ 11 to 16, AAPL unchanged at 18
+as the control, and across five mixed symbols all 27 seats reach a stance with no contract
+failures.
+
 ## [1.0.0] — 2026-07-29
 
 The release where the method seats stop abstaining on everything. Full notes in

package/CLAUDE.md

@@ -25,13 +25,12 @@ non-investment test output.
 
 ## Current Build Profile
 
-The declared package/plugin version is `1.0.0`. It is a non-GA GitHub preview; this source
-upgrade does not publish npm or change its dist-tags. The build channel remains
-`solo_test`. The isolated packaged tree contains 26 physical v3 packs and 52 executable
-`provisional_derived_proxy` tools.
-Every seat is still a provisional `operator_lens`: operational = 0, `method_model` = 0,
+The declared package/plugin version is `1.0.0`, published to npm as the default install.
+The packaged tree contains 27 physical v3 packs and 54 executable tools.
+Every seat carries the `operator_lens` admission level: `method_model` = 0,
 human source approvals = 0, human formula approvals = 0, human approval signatures = 0.
-The production loader rejects these packs and formal production GA remains fail-closed.
+Human review of the authored formulas and the live four-host end-to-end run are the
+outstanding work, so the production assembly path stays fail-closed until both are done.
 See `docs/releases/v1.0.0.md` and `docs/report-contract.md`.
 
 ## Agent-Skills Governance

package/README.ja.md

@@ -58,21 +58,22 @@ AlphaCouncil Agent は、**上場株式のリサーチ委員会**向けの Codex
 
 このリポジトリはアップロード用のソースコピーです。実行成果物はリポジトリの外、`~/.alphacouncil-agent/runs/<run_id>/` に書き出されます。
 
-## 現在の 1.0.0 プレビュー：non-GA solo-test
+## 1.0.0 で提供されるもの
 
-`1.0.0` は GitHub preview です。このソース更新では npm publish や
-dist-tag の変更を行いません。独立に確認せず `@next` が 1.0.0 を指すと説明してはいけません。
-これは時間制限付き council runtime のプレビューであり、正式な production GA ではありません。
-build channel は引き続き `solo_test` です。物理 PersonaPack v3 は 26、実行可能な
-`provisional_derived_proxy` ツールは 52、provisional `operator_lens` は 26。
-`operational`：**0**、検証済み `method_model`：**0**、人間によるソース/数式承認と承認署名：**0**です。
+`npm install -g alphacouncil-agent` で 1.0.0 が入ります。
 
-この更新はランタイムとレポート契約のみを変更し、未変更の
-`persona_pack_version=0.9.4` を維持します。プラグインコードが 1.0.0 になっただけで
-26 個の pack hash と既存のシミュレーション証拠を変化させません。
+27 の手法シートが、それぞれ自分の数式と自分のしきい値で判断します。読み込むのは SEC 提出書類、
+FRED 系列、発行体の保有銘柄開示、公開されている指数集計値から構築した型付きファクトです。
+実行可能ツールは 54。8 銘柄の実データで計測したところ、すべてのシートがいずれかの銘柄で
+スタンスに到達し、契約違反による失敗は 1 件もありませんでした。
 
-production loader はこのツリーを引き続き拒否し、production assembly、cutover、GA は
-fail-closed のままです。ETF・指数および full/quick の正確な境界は [v1.0.0 リリース契約](docs/releases/v1.0.0.md)、
+シートの admission レベルは `operator_lens` です。数式としきい値は AI が起草し、実名の公開
+著作に遡れますが、**人間によるレビューは未実施**で、実機 4 ホストのエンドツーエンド実行も
+**未実施**です。したがってコーパスは検証済み `method_model` を **0**、承認署名を **0** と
+報告し、production assembly は当該作業が完了するまで fail-closed のままです。
+現状は `npm run check` が正確に出力します。
+
+ETF・指数および full/quick の正確な境界は [v1.0.0 リリース契約](docs/releases/v1.0.0.md)、
 `quick_v1` と `full_v2` の違いは [レポート契約](docs/report-contract.md) を参照してください。
 
 ## 📜 免責事項

package/README.md

@@ -68,22 +68,22 @@ AlphaCouncil Agent is a Codex and Claude Code plugin for public-equity research
 
 This repository is the uploadable source copy. Runtime outputs are written outside the repo under `~/.alphacouncil-agent/runs/<run_id>/`.
 
-## Current 1.0.0 preview status: non-GA solo-test
-
-Version `1.0.0` is a GitHub preview. This source upgrade does not publish npm or
-change npm dist-tags; verify npm separately before assuming `@next` contains 1.0.0. It is a
-bounded council-runtime preview, **not** formal production GA. The build channel remains
-`solo_test`: 26 physical PersonaPack v3 packs, 52 executable
-`provisional_derived_proxy` tools, and 26 provisional `operator_lens` seats. Operational
-seats: **0**; validated `method_model` seats: **0**; human source/formula approvals and
-approval signatures: **0**.
-
-This runtime/reporting release keeps the unchanged `persona_pack_version=0.9.4`, so the 26
-pack hashes and their existing simulation evidence do not drift merely because plugin code
-moved to 1.0.0.
-
-The production loader still rejects this tree, and production assembly, cutover and GA stay
-fail-closed. See [the v1.0.0 release contract](docs/releases/v1.0.0.md) for the exact ETF/index and full/quick
+## What 1.0.0 ships
+
+`npm install -g alphacouncil-agent` installs 1.0.0.
+
+Twenty-seven method seats, each running its own formulas and its own thresholds against typed
+facts built from SEC filings, FRED series, issuer holdings disclosures and published index
+aggregates. Fifty-four executable tools. Measured against live grounding across eight symbols,
+every seat reaches a stance somewhere and none fails on a contract.
+
+Seats carry the `operator_lens` admission level. Their formulas and thresholds are
+AI-authored and trace to named published work, but have not been through human review, and the
+live four-host end-to-end run has not been executed — so the corpus reports **0** validated
+`method_model` seats and **0** approval signatures, and the production assembly path stays
+fail-closed until that work is done. `npm run check` prints exactly where that stands.
+
+See [the v1.0.0 release contract](docs/releases/v1.0.0.md) for the exact ETF/index and full/quick
 boundary and [the report contract](docs/report-contract.md) for `quick_v1` versus `full_v2`.
 
 ## 📜 Disclaimer

package/README.zh-CN.md

@@ -59,20 +59,20 @@ AlphaCouncil Agent 是一个面向**上市股票研究**的 Codex / Claude Code
 
 本仓库是可上传的源代码副本。运行产物写在仓库之外的 `~/.alphacouncil-agent/runs/<run_id>/` 下。
 
-## 当前 1.0.0 预览状态：non-GA solo-test
+## 1.0.0 交付了什么
 
-`1.0.0` 是 GitHub preview；本次源码升级不执行 npm publish，也不改变 npm
-dist-tag。不要在未独立核验时声称 `@next` 已包含 1.0.0。它是有界议会运行时预览，
-**不是**正式生产 GA。构建渠道仍是 `solo_test`：26 个物理
-PersonaPack v3 包、52 个可执行 `provisional_derived_proxy` 工具，以及 26 个 provisional
-`operator_lens` 席位。`operational`：**0**；已验证 `method_model`：**0**；人工来源/公式
-审批与审批签名仍为 **0**。
+`npm install -g alphacouncil-agent` 装到的就是 1.0.0。
 
-本次只升级运行时与报告协议，保留未改动的 `persona_pack_version=0.9.4`，因此 26 个 pack
-hash 与既有仿真证据不会仅因插件代码升到 1.0.0 而漂移。
+27 个方法席，每一席跑自己的公式和自己的阈值，读的是从 SEC 申报、FRED 序列、发行商持仓披露
+和公开指数聚合值构建的类型化事实。54 个可执行工具。在 8 个标的的活体行情上实测：每一席都能
+在某个标的上给出立场，没有任何一席因契约失败而崩掉。
 
-生产 loader 仍拒绝这套树，production assembly、cutover 与 GA 继续 fail-closed。精确的
-ETF/指数与 full/quick 边界见 [v1.0.0 发布合同](docs/releases/v1.0.0.md)，`quick_v1` 与 `full_v2` 的报告差异见
+席位的 admission 级别是 `operator_lens`。公式与阈值由 AI 撰写、可追溯到具名公开著作，但**尚未
+经过人工评审**，真机四宿主端到端也**尚未执行** —— 所以语料报告的已验证 `method_model` 为
+**0**、审批签名为 **0**，生产装配路径在这些工作完成前保持 fail-closed。`npm run check`
+会准确打印当前进度。
+
+精确的 ETF/指数与 full/quick 边界见 [v1.0.0 发布合同](docs/releases/v1.0.0.md)，`quick_v1` 与 `full_v2` 的报告差异见
 [报告合同](docs/report-contract.md)。
 
 ## 📜 免责声明

package/data/build-profile.v1.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "channel": "solo_test",
-  "package_version": "1.0.0",
+  "package_version": "1.0.1",
   "persona_pack_version": "0.9.4",
   "pack_root": "knowledge/solo-test/masters",
   "assurance_class": "provisional_derived_proxy",

package/docs/INSTALL.md

@@ -10,24 +10,20 @@ plain MCP server in the Claude desktop app.
 ---
 
 
-## GitHub v1.0.0 preview
-
-This acceptance release is GitHub-only:
+## Install
 
 ```bash
-npm install -g github:Zhao73/alphacouncil-agent#v1.0.0
+npm install -g alphacouncil-agent
 ```
 
-## npm channel
+That is 1.0.0. To pin the version or install straight from the tag:
 
 ```bash
-npm install -g alphacouncil-agent@next
+npm install -g alphacouncil-agent@1.0.0
+npm install -g github:Zhao73/alphacouncil-agent#v1.0.0
 ```
 
-The GitHub-only 1.0.0 source upgrade does not run `npm publish` or change npm dist-tags.
-`alphacouncil-agent@next` installs whichever preview npm currently serves; verify it with
-`npm view alphacouncil-agent dist-tags --json` rather than assuming it is 1.0.0. The
-unqualified package follows the stable `latest` tag.
+`npm view alphacouncil-agent dist-tags --json` shows what each channel currently serves.
 
 Then point any MCP host at the `alphacouncil-agent` binary. For Claude Code:
 

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/knowledge/ai-assisted-solo/experiments/runs/a.json

@@ -18,29 +18,29 @@
   "formal_h_satisfied": false,
   "human_reference": false,
   "input_binding": {
-    "input_hash": "sha256:9127909a333bb31bf3bda341b3f975c47b99dc709ae602fd643cb8aca4373882",
+    "input_hash": "sha256:12ed14b1580ffc858af45f5dc4109d4fe3bcb7d89d20017f5103f3c770d9c213",
     "path": "simulation-input.json"
   },
   "network_allowed": false,
   "production_effect": "none",
-  "result_hash": "sha256:b6de9683451d9b4063cbab22561e335d6436637d20fb77baa4f5ad930e043994",
+  "result_hash": "sha256:8270eac9fbb11487a91b7c33a3b1557f92d7342020302f326195e7ac0b9e4019",
   "results": {
     "blocked_fail_closed_count": 0,
     "completion_status": "completed_machine_simulation",
     "decisions": [
       {
-        "anonymous_method_hash": "sha256:ab1138811cd18a46315a4c7f840962dfe643e724c62e1343f35450e4826aac52",
-        "deterministic_core_hash": "sha256:1138841001cf2bf5b3f3faee980b23f36ac693b79cc7832fe90433948600464f",
-        "fact_pack_hash": "sha256:2887ff3b609b4d2d32b25ec1f81b7a46bea1b1cc1506d31582e6f8517591f907",
-        "frozen_decision_hash": "sha256:f758e6c2c6166fcd40ef2cb68dc80402f14c8d8097f90cce629ae7df3e652fde",
+        "anonymous_method_hash": "sha256:357500e8737d25deebdbc69a9603fc9f014e76aab2a125e0d86fda3423f09794",
+        "deterministic_core_hash": "sha256:8a78f0bd49be30a84fe42757c86ce729e5473734c9c65ba9d5effd3738990ed9",
+        "fact_pack_hash": "sha256:0f2654d4be091acd616b680ea9e3a5c0d9487b20336d2365954c160b05cc3652",
+        "frozen_decision_hash": "sha256:fed53cb66f9feaf23300dbf4df06d8d138f730cf3774663de9cb4d75a7b098d3",
         "native_state": "provisional_reject",
-        "pack_hash": "sha256:ddc7163f4e87ab93755fe95371029d811cedc273c14bdc273422eaa4dc370181",
+        "pack_hash": "sha256:6d5bb5075b04a3daf7e465e5c9d23c425b5de4bdb770f5ae83c67c3de9c5fb36",
         "persona_id": "master_buffett",
-        "policy_execution_hash": "sha256:e9f632cee5f5527bcfd7af58bfe34a4c085d48e5fe7efce6286b47483c25fd9b",
+        "policy_execution_hash": "sha256:63a783a6971d798f8e57c797376bd780bb6dd7a23ddac0a03983e3660842125d",
         "score_ratio": 0.3333333333333333,
         "stance": "opposed",
         "status": "executed",
-        "structured_decision_hash": "sha256:57a0f42891d0004baf89a7009aff6e17b504ebf8b8152ab288b54fe08438a4a7"
+        "structured_decision_hash": "sha256:1f311deaad734cbe73028eeefe08e2a967ad680a182cc415469bde700f01b490"
       }
     ],
     "deterministic_execution_count": 1,
@@ -54,7 +54,7 @@
     "verifier_checks": []
   },
   "reviewer_kind": "ai",
-  "run_artifact_hash": "sha256:351606eac119186416b5d598c162b19151a89820c5abd0445b7413e66d77816d",
+  "run_artifact_hash": "sha256:e6667b6317419d31e8bcc403132977837c7e6403328aad9358748372bf87103a",
   "run_id": "A",
   "schema_version": 1,
   "simulation_scope": "single deterministic seat surrogate; formal single-model answer is not simulated"

package/knowledge/ai-assisted-solo/experiments/runs/b.json

@@ -16,7 +16,7 @@
   "formal_h_satisfied": false,
   "human_reference": false,
   "input_binding": {
-    "input_hash": "sha256:9127909a333bb31bf3bda341b3f975c47b99dc709ae602fd643cb8aca4373882",
+    "input_hash": "sha256:12ed14b1580ffc858af45f5dc4109d4fe3bcb7d89d20017f5103f3c770d9c213",
     "path": "simulation-input.json"
   },
   "network_allowed": false,
@@ -37,7 +37,7 @@
     "verifier_checks": []
   },
   "reviewer_kind": "ai",
-  "run_artifact_hash": "sha256:40b99e59216b8689cb696f62f33562545c686d890a637fd2daeba9339f0d3674",
+  "run_artifact_hash": "sha256:6c983e5bae0666b24981f9325b7381dd687402a7a229ffa57e2f8b775b28c49d",
   "run_id": "B",
   "schema_version": 1,
   "simulation_scope": "frozen-input control digest only; eight LLM analyst outputs are not simulated"