alphacouncil-agent 0.9.2 → 1.0.0

package/docs/plans/v1.0-roadmap.md

@@ -0,0 +1,487 @@
+# AlphaCouncil 升级方案 v0.9.5 → v1.0（第二版）
+
+制定日期：2026-07-28
+基线：`agent/etf-index-master-voices` @ `6ec9ca0`（PR #5，draft，未合并）
+本版推翻第一版的 P2-2「把弃权渲染成太难那一堆」——那个方案回避了真问题。
+
+---
+
+## 0. 真实诊断：三层全空，不是一层
+
+用户的质疑是对的：如果巴菲特看 QQQ 的回复是「这不归我管」，产品就没有意义。
+把三层拆开看，问题比"缺数据"严重：
+
+### 第一层：事实供给（缺 92%）
+
+`mcp/lib/personas-v3/grounding-adapter.mjs` 是全仓库唯一产 typed facts 的地方，只能产 13 个 `fact_id`：
+quote 2 个、options 4 个、SEC screen 7 个。26 席的 `required_fact_types` 大部分不在其中。
+
+```
+可在当前适配器下执行的席位: 1 / 26      （只有 master_natenberg）
+```
+
+**换 AAPL 跑结果一样。**这不是 ETF 特例，是全局缺口。
+
+### 第二层：方法模型（是空壳，这是更根本的问题）
+
+把 26 个 `decision_policy.json` 全量对比，**26/26 完全一致**：
+
+```
+eligibility=0 条 | hard_vetoes=0 条 | rules=2 条 | score_bands=3 档 | native_output_fields=2
+```
+
+巴菲特那一席的"方法"逐字展开是：
+
+```jsonc
+// tools.json：两个工具，operation 都是 identity
+{ "id": "master_buffett.owner_earnings_rebuilder",
+  "inputs": [{"fact_id": "financial.owner_earnings"}],
+  "operation": "identity",
+  "output_id": "financial.owner_earnings" }              // 自己复制给自己
+{ "id": "master_buffett.incremental_returns",
+  "inputs": [{"fact_id": "financial.owner_earnings"}],
+  "operation": "identity",
+  "output_id": "financial.incremental_return_on_capital" } // 所有者盈余"就是"增量ROIC？
+
+// decision_policy.json：两条规则
+owner_earnings > 0        → 1 分
+incremental_roic > 0      → 1 分   （其实是同一个数）
+2/2 → cautious
+```
+
+生成器里 `derivation_policy` 字段写得很老实：`"first_declared_input_to_first_declared_output_identity_v1"`。
+
+**所以即使把数据全补上，巴菲特也只会输出"所有者盈余大于零 → cautious"。** 这不是巴菲特，
+这是脚手架。用户问"客户用它还有啥意义"——在第二层修好之前，诚实的答案是：没有意义。
+
+好消息：**方法设计已经写完了**，在 `data/persona-v3-build-specs.v1.mjs` 里。巴菲特那条有
+6 个 `required_fact_types`、4 个 native states、3 条 `veto_families`（能力圈外 / 杠杆依赖 /
+所有者盈余不可重建）、明确的 `fail_closed_reasons`。生成器
+（`scripts/lib/persona-v3-solo-test-packs.mjs:299-348`）把这些**全部丢掉**，硬编码
+`eligibility: { all: [] }`、`hard_vetoes: []`。缺的是把 spec 变成真策略，不是重新设计方法。
+
+### 第三层：表达（机器诊断文案）
+
+`巴菲特视角临时操作视角无法评估 QQQ：no_required_fact_types_present`
+
+---
+
+## 1. 关键洞察：穿透聚合是巴菲特自己的发明，而且必须做在事实层
+
+### 1.1 "Look-through earnings" 是巴菲特 1990 年致股东信里的原创概念
+
+他持有一堆公司的部分股权，会计利润只体现分红，于是他自己定义了「穿透盈余」：
+按持股比例把被投公司的留存收益加回来看。**用穿透法评估 QQQ 不是把方法硬套在 ETF 上，
+就是他本人处理"我拥有一百家生意的一部分"的标准做法。**这解决了合规和方法论正当性两个问题。
+
+### 1.2 聚合只能做在事实层（DSL 层做不了，这反而是好消息）
+
+决策 DSL 的算子白名单是
+`eq/neq/gt/gte/lt/lte/date_*` + `exists` + `all/any/not`，操作数只能是
+`{fact_id}` / `{output_id}` / `{literal}`（`literal` 必须是标量，数组直接拒），
+条件层不支持算术。工具层的 `sum/mean` 吃的是固定 arity 的操作数列表，不是集合。
+
+**结论：DSL 永远不可能对 N 个持仓做加权聚合。**
+所以聚合必须在 `grounding-adapter` / 新的 `funds.mjs` 里做，产出**一个**
+`financial.owner_earnings` 事实（带 `derivation: "rederived"` + `calculation_hash` + `coverage_weight`）。
+
+**而这正是好消息：** 一旦事实层把 QQQ 的穿透 `financial.owner_earnings` 供上，
+**26 个 pack 一个字节都不用改就能在 ETF 上执行。** 不需要 instrument 条件化的 pack 变体，
+不需要动 schema，不需要重签 hash，不需要动选席回执的 pack_hash 审计链。
+
+（我评估过四种 instrument 条件化方案：pack 内多份 policy 8-10 天 / `required_fact_types` 改 map
+10-14 天 / 平行包集 15-20 天且撕裂审计链 / `research_model` 做成 typed fact 走 eligibility 3-4 天。
+但做完事实层之后，前三种都不需要了，第四种只在"某方法必须显式拒绝某类标的"时才用。）
+
+---
+
+## 2. 终点长什么样（用今天抓到的真实数字）
+
+已验证可取的真实数据（2026-07-27/28 实测）：
+
+| 数据 | 值 | 来源（已验证可用） |
+|---|---|---|
+| QQQ 持仓 | 108 只，AAPL 权重 8.264548% | `dng-api.invesco.com` daily |
+| NDX 滚动 P/E | **33.05** → 盈利收益率 **3.03%** | WSJ `mdc_peAndYields` |
+| NDX 前瞻 P/E | 25.12 → 3.98% | 同上 |
+| NDX 股息率 | 0.58% | 同上 |
+| 10 年期国债 | **4.69%** | FRED `fredgraph.csv?id=DGS10` |
+| QQQ 费率 | 0.20% | Invesco |
+
+**巴菲特席位应该输出的东西（Tier A 原生判断）：**
+
+> **巴菲特方法** — 立场：`opposed` ｜ 置信度：medium ｜ 意向：`would_pass`
+>
+> 我看到的是：这一百零八家公司的穿透盈余收益率是 **3.03%**（滚动口径，覆盖权重 100%），
+> 十年期国债给我 **4.69%**。我还要为持有它每年付 0.20%。
+>
+> 用我的标准来衡量：我在 1999 年那篇文章里说过，股票的价值最终要和利率比。
+> 现在这个篮子的盈利收益率比无风险利率还低 **1.66 个百分点**，而且我承担的是
+> 一个前十大占五成、集中在少数几家公司的波动组合。前瞻口径好一些（3.98%），
+> 但那要靠分析师的预测兑现，那不是我的安全边际。
+>
+> 所以我会不会买：**不会，现在不会。** 这不是说纳斯达克的生意不好——里面确实有几家
+> 我很喜欢的公司。是这个价格不给我任何余地。我推荐给我太太的是更宽的标普 500 篮子，
+> 而且是在任何价格上定投；作为一次性配置决策，我在这个价格上会等。
+>
+> 什么会让我改主意：盈利收益率回到国债之上 200 个基点（对应 NDX 滚动 P/E 约 15），
+> 或者利率降到 3% 以下而盈利没有同步下滑。
+>
+> 我和谁分歧：德鲁肯米勒方法看的是流动性脉冲而不是估值，他可能在我说贵的时候继续持有——
+> 这是方法差不是信息差，我们看的是同一份数据。
+>
+> *（本段为方法模型的第一人称推演，非本人言论或授权观点。数据源 ID：wsj:ndx_pe:2026-07-24、
+> fred:DGS10:2026-07-24、invesco:qqq_holdings:2026-07-27）*
+
+**格雷厄姆席位**（同样是 Tier A）：盈利收益率 3.03% vs AAA 公司债收益率，
+他的防御型投资者判据要求前者 ≥ 后者的 2 倍 → 明显不通过，`opposed`，理由是一个数。
+
+**芒格席位**（Tier B 穿透）：不评组合，评前十大占 51% 权重的那几家的激励结构与失败路径，
+按权重汇总"我对其中 X% 的权重有信心"。
+
+**这才是产品的意义。**每个数字有 source_id，每个判断可证伪，每一席的分歧是真分歧。
+
+---
+
+## 3. 三根支柱
+
+### 支柱 A — 事实供给层（不碰 pack，零 hash 风险，破 0 个测试）
+
+这是唯一"改了立刻见效且不会引发重签风暴"的一层。先做完这层再动任何 pack。
+
+#### A1. macro → typed facts（最高 ROI，零新数据源）
+
+`macro.mjs` 已经在抓五组市场定价序列，但快照没写 `public_at`，
+适配器整块跳过（`grounding-adapter.mjs:370` 记 `not_converted`）。
+
+- `macro.mjs` 每 block 输出 `public_at`（取组内最早 `quote_time`）+ `source_ids`
+- 新增 `macroFacts()`：`macro.liquidity_impulse`、`macro.growth_regime`、
+  `macro.real_rate`、`macro.credit_spread`、`macro.term_structure_slope`
+- 补 FRED keyless 通道（**已验证**：`fredgraph.csv?id=` 免密钥，
+  `DGS10 DGS2 DGS3MO T10Y2Y T10Y3M DFII10 T5YIE DFF SOFR BAMLH0A0HYM2 VIXCLS` 全部 200；
+  `api.stlouisfed.org` 才需要 key。多 series 会返回 ZIP，逐个拉）
+
+**解锁**：`master_druckenmiller`、`master_dalio`。约 150 行 + 单测。
+
+#### A2. `mcp/lib/funds.mjs` — ETF 持仓与穿透聚合
+
+**已验证可用的发行商端点（全部免密钥，四条 URL 都是新路径，网上流传的旧地址已失效）：**
+
+```bash
+# iShares（IVV/IWM/EFA/AGG/TLT/HYG…）日度 T-1
+https://www.ishares.com/us/products/239726/x/latest-holdings.csv
+# State Street（SPY/XLK…）日度，必须 -L 跟 301
+https://www.ssga.com/us/en/intermediary/library-content/products/fund-data/etfs/us/holdings-daily-us-en-spy.xlsx
+# Invesco（QQQ/QQQM…）日度
+https://dng-api.invesco.com/cache/v1/accounts/en_US/shareclasses/46090E103/holdings/fund?idType=cusip&interval=daily&productType=ETF
+# Vanguard（VOO/VTI…）仅月末，每页 500 条
+https://investor.vanguard.com/investment-products/etfs/profile/api/VOO/portfolio-holding/stock
+```
+
+**必须写进代码的反爬陷阱（每条都是实测的，漏一条就静默出错）：**
+
+1. **iShares 旧 `.ajax` 路径是静默陷阱** —— 仍返回 `HTTP 200` + `Content-Type: text/csv`，
+   但 body 是 2.2MB 的 HTML 产品页，换任何 UA 都一样。**必须校验首行内容，不能只看状态码。**
+2. **Invesco 的 UA 逻辑是反的** —— `www.invesco.com` 发 Chrome UA 或空 UA → `HTTP 406` 零字节；
+   发默认 `curl/8.x` 或 `node-fetch` → 200。**千万别伪装浏览器。**
+3. **Invesco 参数陷阱** —— 漏 `interval=daily` 拿到 3 天前的旧数据；误加 `loadType=initial`
+   静默截断成前 10 条；`idType=ticker` 只对 QQQ 有效，统一用 CUSIP。
+4. Vanguard 响应里的 `next` 指向已废弃的 `api.vanguard.com`，翻页要自己拼
+   `?start=501&count=500` 打在 `investor.vanguard.com`。
+5. SEC 任何请求必须带 `User-Agent: app contact@email`，否则 403。
+
+**费率 / AUM / NAV / 份额：**
+- iShares product-screener 一次拿 532 只基金的 `fees` / `navAmount` / `totalNetAssets` / `cusip`
+- SSGA fundfinder 一次拿 180 只 SPDR 的 `ter` / `nav` / `aum`（份额 = aum/nav）
+- **Vanguard 和 Invesco 没有 AUM/份额端点**（Invesco 的 `/nav`、`/profile` 全 501）→
+  用持仓市值求和，或 SEC N-PORT 的 `netAssets` 兜底
+
+**资金流（无免费直接源，必须推导）：** `flow = Δshares_outstanding × NAV`。
+实测验证过：IVV 份额 2026-07-24 的 1,167,300,000 → 07-27 的 1,167,700,000，
+Δ+400,000 股 × NAV 741.66 ≈ 净流入 $296.7M。
+**局限**：只有 iShares 和 SSGA 有日度份额，Vanguard/Invesco 没有 → 那两家的 flow 记为 gap，不许估。
+
+**SEC N-PORT 兜底（重要更正：是季度不是月度）：**
+表单名叫 "Monthly Portfolio Investments Report"，但公开披露实际**季度**，滞后 50-59 天。
+另一个坑：`company_tickers.json` 里**查不到 IVV 和 VOO**（它们是信托下的 series），
+必须用 `company_tickers_mf.json`（IVV→CIK 1100663/S000004310，VOO→CIK 36405/S000002839）。
+
+**新增 typed facts：**
+```
+fund.holdings_as_of  fund.top_ten_weight  fund.sector_concentration_hhi
+fund.expense_ratio   fund.aum             fund.shares_outstanding
+fund.flow_20d        fund.premium_discount fund.tracking_difference(nullable)
+fund.lookthrough_coverage_weight
+```
+
+**穿透聚合（本方案的核心）：** 对前 N 大持仓（覆盖权重 ≥60%）批量取基本面，
+按权重聚合成**单个**经营公司事实：`financial.owner_earnings`、
+`financial.return_on_equity_10y`、`valuation.revenue_growth` 等。
+每个聚合事实必带 `lineage.calculation_hash` + `fund.lookthrough_coverage_weight`。
+
+**硬规则写进代码，不是写进 prompt：** 覆盖权重 < 50% 时**不生成**任何 look-through 派生事实，
+只记 diagnostics。现在这条只是 prompt 里一句话，模型可以无视。
+
+**绝不做的事：** 把成分股财报相加成"ETF 营收/EPS"。加权只允许出现在比率型指标，
+且 `ratio_denominator` 必须写明加权口径。
+
+#### A3. `mcp/lib/index-aggregate.mjs` — 指数
+
+**成分来源（法务上唯一稳妥的免费路径）：用跟踪 ETF 的持仓做代理**，
+^GSPC→IVV/SPY，^NDX→QQQ，^DJI→DIA，并在 fact 的 `derivation` 和报告里**显式声明是 ETF 代理**。
+理由：S&P 500 / DJIA 的成分与权重是 S&P Dow Jones Indices 的授权资产，
+datahub / stockanalysis / Finviz 都是无授权转载；Wikipedia 是唯一有明确开放许可（CC BY-SA）的，
+但产品化仍有风险。发布"基金持仓"而非"指数成分名单"是业界标准规避做法。
+（`api.nasdaq.com/api/quote/list-type/nasdaq100` 实测可用且与 QQQ 持仓完全对上，
+但**必须带非默认 UA**，默认 curl UA 会 HTTP/2 INTERNAL_ERROR。）
+
+**估值 / 广度 / 期权（已验证端点）：**
+```bash
+# 指数滚动+前瞻 PE（一次拿 SP500/NDX/Russell2000）
+https://www.wsj.com/market-data/stocks/peyields?...&type=mdc_peAndYields
+# 涨跌家数/新高新低/TRIN
+https://www.wsj.com/market-data/stocks/marketsdiary?...&type=mdc_marketsdiary
+# CBOE put/call（日期必须是交易日，非交易日 403，需回退查找）
+https://cdn.cboe.com/data/us/options/market_statistics/daily/YYYY-MM-DD_daily_options
+https://cdn.cboe.com/api/global/us_indices/daily_prices/VIX_History.csv
+```
+WSJ 的 `mdc_*` 是未公开内部 API，**必须加 schema 校验和降级路径，不能当契约用**。
+
+**Damodaran 数据集（可机读）：**
+`pages.stern.nyu.edu/~adamodar/pc/implprem/ERPbymonth.xlsx`（月度 ERP，注意在 `/pc/implprem/`
+而**不在** `/pc/datasets/`），`/pc/datasets/histimpl.xls`（年度）。
+`.xls` 是老 BIFF 格式要用 `xlsx` 包；xlsx 空单元格会被省略，**必须按列字母对齐，不能按位置取**。
+
+**唯一的硬缺口：广度（% above 200dma）。** Finviz 的 screener 组合参数在 robots.txt 里被
+`Disallow: /screener?*` 明确禁止（白名单不含所需参数），自建 dashboard 可以，产品化不建议。
+自己算需要 503 只 × 260 天日线 ≈ 13 万点，而没有验证到免密钥的批量日线源。
+**这块要预算一个行情商，或者用 WSJ marketsdiary 的涨跌家数做低保真代理并标注口径。**
+
+**⚠️ 口径警告（必须写进代码注释）：** 同一天的 S&P 500 滚动 P/E，
+WSJ 报 25.17、multpl 报 28.53、iShares IVV 报 29.80 —— 三种不同盈利口径
+（WSJ 基准 / GAAP as-reported TTM / 组合调和平均）。**混用会让面板看起来像坏了。**
+一个 fact 只能有一个口径，`ratio_denominator` 必须写死来源。
+
+**新增 typed facts：**
+```
+index.constituent_count  index.aggregate_pe_ttm  index.aggregate_pe_forward
+index.aggregate_earnings_yield  index.dividend_yield  index.breadth_advance_decline
+cycle.valuation_percentile  expectations.consensus_dispersion
+factor.value_exposure  positioning.crowding  options.put_call_ratio
+macro.aaa_corporate_yield  macro.long_bond_yield  valuation.implied_erp
+```
+
+#### A4. SEC 派生（经营公司侧）
+
+从已有 CompanyFacts 机械派生，全部带 `calculation_hash` + 显式假设：
+
+| fact_id | 算法 | 解锁 |
+|---|---|---|
+| `financial.owner_earnings` | 净利 + D&A − 维持性资本开支（维持性用 3 年 capex 中位数 × 0.7 代理） | **buffett** |
+| `financial.net_current_asset_value` | 流动资产 − 全部负债 | graham |
+| `valuation.downside_asset_value` | 有形账面 + 现金 − 债务 | klarman |
+| `valuation.downside_floor` | min(NCAV, 有形账面, 5 年最低 EV/EBIT 对应价) | pabrai |
+| `valuation.revenue_growth` | 5 年 CAGR + 最近 4 季 YoY | damodaran |
+| `short.borrow_cost` | 无免费源 → **不做，记为已知缺口** | forensic_short 继续弃权 |
+
+---
+
+### 支柱 B — 真方法模型（"有没有意义"的分水岭）
+
+#### B0. 操作纪律（不遵守每次都会红）
+
+pack 是 100% 机器生成的，**手改无效**——生成器会在内存里重建全部文件逐字节比对。
+唯一合法路径：改 `data/persona-v3-build-specs.v1.mjs` + `knowledge/solo-test/persona-v3-solo-test-formulas/`
++ 生成器，然后：
+
+```bash
+npm run persona:solo-test:build       # 26 个 pack 全量重生成
+npm run persona:ai-simulations:write  # 8 个仿真 run 重生成
+npm run check                         # selfcheck 三道闸 + 全测试
+```
+
+另外：动 `runtime.mjs` / `deterministic-executor.mjs` / `typed-facts.mjs` / `registry.mjs`
+这四个文件中的任何一个，都必须重跑机器仿真（它们的字节 hash 被绑进仿真树）。
+
+#### B1. 生成器改造：让 spec 里的设计真正落地
+
+`scripts/lib/persona-v3-solo-test-packs.mjs:299-348` 现在硬编码
+`eligibility: { all: [] }`、`hard_vetoes: []`，把 build-spec 里已经写好的
+`veto_families` 和 `native_decision_contract.eligibility_facts` 全丢了。改成从 spec 生成。
+
+**一个必须绕开的陷阱：** 当前 `scoring.min_coverage = 1`，
+**任何一条规则 uncomputable → 整席直接 `out_of_scope`**。
+所以方法判据要走 `eligibility` / `hard_vetoes`（它们有独立的 uncomputable 出口），
+不要全塞进 scoring rules，否则缺一个字段就整席哑火——这正是现在 25 席弃权的机制。
+
+#### B2. 写真公式，替换 identity 桩
+
+DSL 条件层不支持算术，所以每个判据要拆成"工具算数 + 条件比数"两步。
+可用算子：`add subtract multiply divide sum mean min max abs negate clamp`（标量，固定 arity）。
+条件层支持 **fact vs fact 直接比较**（实测通过），这是关键——
+"盈利收益率 > 国债收益率" 可以直接写成两个 fact 的 `gt`，不需要先算差值。
+
+**首批 8 席（在个股和 ETF/指数上都能出真判断，优先做）：**
+
+| 席位 | 核心判据（可直接用现有数据实现） |
+|---|---|
+| `master_buffett` | 穿透盈余收益率 vs 10y 国债；集中度；费率拖累；杠杆依赖 veto |
+| `master_graham` | 盈利收益率 ≥ 2 × AAA 债收益率（防御型投资者判据）；NCAV |
+| `master_marks` | 估值分位 + 风险偏好读数 → 周期温度计 |
+| `master_damodaran` | implied ERP vs 历史分位（他自己每月发布这个数） |
+| `master_dalio` | 增长/通胀四象限 + 当前 regime → 股票指数暴露建议 |
+| `master_druckenmiller` | 流动性脉冲方向 + 拐点 |
+| `master_asness` | 价值利差分位 + 因子暴露 |
+| **`master_bogle`（新增）** | 期望收益 = 股息率 + 盈利增长 ± 估值变化；成本至上 |
+
+**为什么必须新增博格：** 26 席里**没有一个是为指数设计的方法**，而这是 ETF 用户唯一最想要的一席。
+博格的收益分解（投资回报 vs 投机回报）能直接给出 QQQ 的十年期望回报数字，
+所有输入（股息率 0.58%、盈利增长、P/E 33.05 的均值回归）都已经在 A3 里备齐。
+新增一席要改 `CANONICAL_MASTER_COUNT` 26→27 及若干处硬编码 26 的断言
+（`runtime-release-integrity.mjs:288,352-361`、`staging.mjs`、几个 release 测试），
+以及 profile 里的 `physical_solo_packs` / `ai_formula_cross_reviews` 数字。
+**这是全案唯一值得付"改 26 常量"代价的改动。**
+
+**第二批 12 席（Tier B，走穿透）：** munger / li_lu / fisher / duan_yongping / lynch /
+klarman / pabrai / burry / ackman / cathie_wood / forensic_short / aschenbrenner。
+它们的方法是单公司的，在 ETF 上跑前十大持仓再按权重汇总，输出
+"我对其中 X% 的权重有信心 / 有疑虑"。
+
+**第三批 6 席：** simons / soros / thorp / taleb / natenberg / sinclair —— 量化与波动率方法，
+指数是它们最好的场景，需要的是 A3 的分布与期权数据。
+
+**诚实弃权保留：** `master_jhunjhunwala`（印度市场方法）在美国科技指数上真的不适用。
+弃权应该是少数且有具体理由的，不是默认状态。
+
+#### B3. AI 交叉复核的连锁成本
+
+`data/persona-v3-ai-assisted-solo-profile.v1.json` 写死
+`ai_formula_cross_reviews: 52`（26 席 × 2 工具，每份 3 个独立角色）。
+每席从 2 个工具加到 3 个 → 需要 78 份复核，profile 数字和全部 index/manifest hash 要同步更新。
+**排期时把这块算进去，它比写公式本身更花时间。**
+
+---
+
+### 支柱 C — 表达层
+
+#### C1. 五段式第一人称（`voice_mode`）
+
+`masterVoicePrompt`（`prompts.mjs:249`）的输出契约改成读者视角：
+
+```json
+{
+  "master": "master_buffett",
+  "acknowledged_stance": "<必须等于冻结立场>",
+  "position_intent": "would_buy | would_add | would_hold | would_pass | not_in_my_circle",
+  "voice": {
+    "what_i_see": "…（只引用 evidence 里的事实 + source_id）",
+    "how_my_method_reads_it": "…（把 typed facts 映射到自己的判据，给出具体数字）",
+    "would_i_buy": "…（明确、可证伪）",
+    "what_changes_my_mind": "…（给出触发阈值，不是空话）",
+    "where_i_disagree": "…（说明是信息差还是方法差）"
+  },
+  "source_ids": [...], "confidence": "high|medium|low"
+}
+```
+
+`position_intent` **由冻结立场机械派生**：建 `stance → allowed intents` 表，
+模型只能在允许集合里选，选错直接拒（复用现有拒绝 stance 不符的机制）。
+冻结立场的安全性不降级。
+
+#### C2. 报告结尾三层递进
+
+```
+## 大师席位怎么看
+### 有判断的（N 席）        ← 每席一个小节，完整五段式，按 intent 强度排序
+### 分歧点                 ← 只列真正立场相反的两席对撞 + 是信息差还是方法差
+### 说这不归我管的（M 席）   ← 合并成一段散文，不是 25 行表格
+```
+
+`method_statement_coverage` 门相应改成"每个 ID 出现在文中"而非"每席独立一行"。
+
+#### C3. 相关性警告保留并前置
+
+`masterCorrelationNote`（"这些席位不是独立样本，立场分布不能当票数"）必须留在最前面。
+第一人称化会天然诱导读者把它当 N 个独立意见，**警告比现在更重要，不是更不重要。**
+
+#### C4. 命名与合规
+
+- 标签从 `巴菲特视角临时操作视角` 简化为 **`巴菲特方法`**
+  （"临时操作视角"是内部成熟度术语，塞进 metadata 括号，不该出现在读者面前）
+- 章节一次性声明：`以下为方法模型的第一人称推演，非本人言论或授权观点`
+- 文案永远说"这套方法会……"，不说"巴菲特现在认为……"
+- **真人第一人称断言不做**——"沃伦·巴菲特认为 QQQ 该买"这句话事实上就是假的。
+  第一人称写的是方法的口吻，这个边界可辩护。
+
+---
+
+## 4. P0 — 合并前必修（与三根支柱独立，1 天）
+
+1. **分类器 fail-open → fail-closed**（`instruments.mjs`）。实测：无 Yahoo 元数据时
+   `SPY/QQQ/VOO` 全部 `plain_us_ticker_fallback → equity, secFacts=true`；
+   `IVV` 因 `iShares Trust` SIC 6726 走 `sec_filer_sic → equity`；
+   `VOO` 因 `Vanguard Index Funds` 走名称启发式 → `index`，期权链被误关。
+   改：SIC 6722/6726/6770 前置判基金；`index fund`/`mutual fund` 排在裸 `index` 前；
+   `plain_us_ticker_fallback` 返回 `unknown`。
+2. **ja/ko 永久 `needs_revision` 死锁**。用已有的
+   `<!-- alphacouncil:recorded-master-bench:v1:sha256... -->` 锚点定位系统段，别靠标题别名匹配。
+3. **陈词能劫持章节**。`normalizeMasterVoice` 出口统一转义行首 `#`。
+4. **`not_applicable` 英文硬编码**渗进多语报告 → 走 `localized()`，
+   `instrumentResearchChecklist` 补 ja/ko。
+5. **状态口径不一致**（`status.json` 说 complete、辩论门说缺席）→ 抽共用判定函数。
+6. **性能回退**：`orchestrator.mjs:397` 只对立场可判定的席位起 voice worker。
+   0.9.4 里 26 席是零模型调用的确定性完成，0.9.5 每席加一次生成 + 一次 MCP 写入，
+   在没有 spawn 能力的 Codex 上全部串行 → 墙钟时间从 15-28 分钟涨到 28-55 分钟。
+
+---
+
+## 5. 排期与验收
+
+**1.0.0 的定义**：26 席在任何标的（含 ETF/指数）上都给出可证伪的真实判断。
+客户端/终端/API 不是 1.0 的门槛，它们是 1.1 之后的分发问题 —— 一个说不出话的委员会，
+包装成桌面应用也还是说不出话。
+
+| 里程碑 | 内容 | 工期 | 验收标准 | 状态 |
+|---|---|---|---|---|
+| **1.0.0-a** | P0 六项 | 1 天 | CI 绿 + 四语报告门 + 无元数据分类矩阵 | ✅ 已完成 `6840d38` |
+| **1.0.0-b** | 支柱 A1 macro→typed facts | 1 天 | 可执行席位 1/26 → 3/26 | ✅ 已完成 `229f2e9` |
+| **1.0.0-c** | 支柱 A2 `funds.mjs` 持仓穿透 | 3-4 天 | QQQ 产出穿透 `financial.owner_earnings`，覆盖权重 ≥60% |  |
+| **1.0.0-d** | 支柱 A3 指数聚合 + A4 SEC 派生 | 3-4 天 | 适配器 fact id 从 22 → ≥35 |  |
+| **1.0.0-e** | 支柱 B 首批 8 席 + 新增博格 | 7-10 天 | QQQ ≥8 席非 out_of_scope 且每条判据有 source_id |  |
+| **1.0.0-f** | 支柱 B 第二三批（穿透 + 量化波动率） | 5-7 天 | QQQ ≥20 席有实质输出，弃权 ≤3 席且各有具体理由 |  |
+| **1.0.0** | 支柱 C 表达层 + 发布 | 3-5 天 | 巴菲特席位对 QQQ 输出第 2 节那段话的结构，数字全部带 source_id |  |
+| 1.1.0 | 引擎抽离 + 终端版 | 5-7 天 | 终端版与 MCP 版报告字节级一致 |  |
+| 1.2.0 | HTTP API + Web + OAuth | 10-14 天 | 无 key 落盘/进前端；配额熔断可验证 |  |
+
+**1.0.0 总计约 4-6 周。**
+
+### 已完成部分的实测结果
+
+`1.0.0-a`：782 → 792 测试全绿，`npm run check` EXIT=0，Integrity passed，8/8 机器仿真无漂移。
+分类器矩阵实测：无元数据时 SPY/QQQ/VOO 由 `equity, secFacts=true` 改为 `unknown, secFacts=false`；
+IVV（iShares Trust, SIC 6726）由 `equity` 改为 `etf`；VOO（Vanguard Index Funds）由 `index`
+改为 `fund_lookthrough`，期权链恢复。
+
+`1.0.0-b`：9 个宏观事实进入 fact pack，零 diagnostics。2026-07-28 实测值 ——
+10y 国债 4.69%、AAA 公司债 5.52%、HY OAS 2.79%（3 年期分位 18.9%）、
+净流动性 $5.92T（91 天 +3.80%）、regime = `rising_growth_falling_inflation`。
+`macro.aaa_corporate_yield` 和 `macro.long_bond_yield` 正是 1.0.0-e 里格雷厄姆和巴菲特判据要用的基准。
+
+### 客户端 / 终端版（简述，细节见前一版方案）
+
+先抽引擎：`mcp/lib/engine/runCouncil(symbol, opts, onEvent)` 发结构化事件流，
+`adapters/{mcp,http,cli}.mjs` 三个壳共用。终端版用 Ink 渲染 N 席位状态灯 + 进度。
+v1.0 的 OAuth 分两层：用户登录用 GitHub/Google（`openid-client`，httpOnly cookie）；
+数据源侧 Tiingo/Polygon 用 API key，券商侧 Schwab/IBKR 走真 OAuth。
+**key 一律服务端环境变量，绝不进前端、绝不进 run artifacts；现有 keyless 路径保留为默认降级。**
+多用户后 run-store 从 `linkSync` 文件锁换 SQLite。token 配额熔断第一天就要有。
+
+---
+
+## 6. 一句话
+
+当前 26 席里只有 1 席能执行，而那 1 席的"方法"是 `identity(x) > 0`。
+**三层都是空的：事实层缺 92%，方法层是脚手架，表达层是机器诊断。**
+顺序不能反 —— 先补事实（不碰 pack，零风险），再写真方法（这是"有没有意义"的分水岭），
+最后做表达。做完前两层，巴菲特看 QQQ 会说"盈利收益率 3.03%，国债 4.69%，我不会买"，
+而不是"这不归我管"。

package/docs/releases/v0.9.3.md

@@ -0,0 +1,86 @@
+# AlphaCouncil Agent v0.9.3 — Bounded Full Council and Complete Handoff (Non-GA)
+
+`v0.9.3` is a non-GA runtime and reporting correction released as a GitHub prerelease.
+This acceptance release does not publish npm or mutate dist-tags. It preserves `full_v2`
+and `quick_v1`; it does not promote any PersonaPack
+seat, relax the selection gate or claim production GA.
+
+## Why 0.9.3 exists
+
+Earlier full headless runs could take substantially longer than the useful user window:
+the eight evidence seats were concurrency-limited, Bull/Bear sides were awaited serially,
+and full had no global queue-to-persistence deadline. The concise handoff could also sample
+analyst groups and omit selected Master Bench results even when their artifacts existed.
+Some v3 seats completed only through the deterministic policy, so users reasonably expected
+an individual method explanation but saw no dedicated model-worker output.
+
+Those are product defects, not investment conclusions. `v0.9.3` changes scheduling,
+visibility and terminalization while preserving the evidence and maturity boundaries.
+
+## Full headless runtime contract
+
+Plugin-managed headless `analyze_symbol(council_mode="full")` now has a hard maximum of
+1,800,000 ms from durable queueing through terminal artifact persistence:
+
+- all eight mandatory evidence workers start in one parallel wave;
+- the evidence barrier remains fail-closed after one bounded parse-only repair;
+- each selected physical v3 method first executes its deterministic policy and freezes its
+  stance, then launches one isolated voice worker for that stable ID;
+- the voice worker may explain the frozen result in the run language but cannot change the
+  stance, invent missing typed facts or speak as the real named person;
+- Bull and Bear launch in parallel within each of the three rounds, with a barrier between
+  rounds and exact Round-2-question to Round-3-answer binding;
+- the PM starts only after both Round-3 sides pass, and deterministic final assembly shares
+  the same global deadline.
+
+A caller or environment can lower the limit, never raise it. At deadline expiry the server
+stops opening downstream work and persists a terminal fail-closed `incomplete` run naming
+every timed-out, failed and skipped role. Thirty minutes therefore guarantees a durable,
+auditable terminal state; it does **not** guarantee that all seats complete when search,
+model transport or external data providers are unavailable or slow.
+
+The deadline belongs to plugin-managed headless `analyze_symbol`. A visible-host run created
+through `plan_visible_run` is scheduled by the external host; the plugin cannot force-stop
+those host subagents and makes no 30-minute promise for that path.
+
+## Complete user handoff
+
+The full `user_response.md` no longer hides the council behind a three-group synopsis. It
+must visibly include:
+
+- a system-owned price snapshot with price, currency, quote timestamp, exchange/feed and
+  source when available, or an explicit unavailable-data gap;
+- every selected stable master ID, its frozen stance and its isolated voice-worker
+  explanation/status;
+- all eight mandatory analyst task IDs, statuses and summaries;
+- key earnings, forward expectations, company/industry news, valuation, position guidance,
+  invalidation conditions, terminal/report-quality state, elapsed/deadline state and paths.
+
+Master output remains a **recorded provisional method-seat result**. It is not a quotation,
+endorsement, current statement or simulated personal advice from the named person.
+
+System-owned catalog/report/handoff labels and failure text support `zh-CN`, English,
+Japanese and Korean. Worker prompts receive the run language. Stable IDs and JSON field
+names remain English for artifact compatibility.
+
+## Quick contract
+
+`quick_v1` remains explicit, plugin-managed and bounded to 600,000 ms. Its fixed four-seat
+evidence wave, 1-4 method limit, one parallel Bull/Bear statement and short PM are unchanged.
+It still rejects `all`, does not run three-round exact Q&A or adversarial verifiers, and
+cannot be represented as `full_v2`.
+
+## Assurance boundary
+
+- Build channel: `solo_test`.
+- `production_eligible=false`.
+- `method_model_eligible=false`.
+- Physical provisional packs: 26.
+- Provisional `operator_lens`: 26.
+- Operational seats: 0.
+- Validated `method_model` seats: 0.
+- Human source/formula approvals and approval signatures: 0.
+
+One worker per selected method makes each recorded result visible; it does not create 26
+independent base models, prove behavioral differentiation or promote a seat's maturity.
+Formal production GA remains fail-closed.

package/docs/releases/v0.9.4.md

@@ -0,0 +1,79 @@
+# AlphaCouncil Agent v0.9.4 — Locale-Consistent Council Output (Non-GA)
+
+`v0.9.4` is a non-GA GitHub prerelease that corrects the locale contract exposed by the
+post-release QQQ Stage 0 acceptance. It does not publish to npm or change npm dist-tags.
+
+## Why 0.9.4 exists
+
+The `v0.9.3` runtime correctly bounded a plugin-managed full council to a thirty-minute
+terminal state and made every selected method-seat statement visible. Its selection layer
+still had a serious observability defect: a `zh-CN` catalog returned English `method` copy,
+Japanese and Korean silently fell back to English, `auto` did not infer the prompt language,
+and confirmation text was always English. A structurally complete English PM report could
+also pass `report_quality` for a Japanese or Korean run.
+
+Those are product defects, not investment findings.
+
+## Selector and receipt corrections
+
+- `zh-CN`, English, Japanese and Korean resolve to one canonical locale before catalog,
+  intent and receipt hashes are created.
+- `auto` infers Chinese, Japanese and Korean scripts from the unchanged run prompt.
+- Unsupported explicit selector locales fail with `UNSUPPORTED_SELECTION_LANGUAGE`; the
+  runtime no longer labels an English fallback as customer-language output.
+- Every one of the 26 physical solo-test manifests carries four-locale title, identity,
+  method and best-for copy. All 26 Chinese method descriptions are now Chinese rather than
+  copied English, and reader-facing `best_for` no longer exposes machine snake-case domain
+  IDs in Chinese, Japanese or Korean.
+- Human-facing maturity has `maturity_label`; the stable machine enum remains unchanged.
+- Selection and confirmation text is localized, while stable IDs, receipt tokens, hashes,
+  JSON keys and maturity enums remain machine-stable.
+- Receipt consumption revalidates the complete selection-record binding and recomputes
+  `selection_hash`; a tampered hash or crossed record fails before a run is created or the
+  one-time receipt is consumed.
+
+## Worker and report language integrity
+
+- Plugin-managed Evidence, dedicated method voice, Bull/Bear and PM packets are checked for
+  the requested reader language. A wrong-language response receives one bounded parse-only,
+  no-search repair opportunity and otherwise fails closed. Visible-host record tools reject
+  wrong-language packets before writing or marking a seat complete so the host can retry it.
+- The language audit treats Han-only fragments as shared script instead of claiming that
+  every Kanji sentence is Chinese. Kana and Hangul take precedence, and English must contain
+  dominant English prose rather than a few company names or finance acronyms.
+- Quick PM now uses the same parse/language/repair path as Bull and Bear. A real debate
+  timeout or transport failure produces a localized failure packet, never a fictitious
+  `DRY_RUN`, and reader-language mismatch remains distinct from malformed JSON.
+- Japanese and Korean timeout, malformed-output, deterministic method-decline and PM
+  fallback text is localized. Failure diagnostics remain separate from investment evidence.
+- `report_quality.json` records `requested_locale`, `observed_locale`, `language_status`,
+  target-script counts and mismatched sections. A complete English report cannot pass a
+  Japanese or Korean run.
+- The system-owned Master Bench heading no longer appends English to non-English headings,
+  and delayed-price labeling no longer leaks provider English notes into localized handoff.
+- Full visible-host recording requires all six Bull/Bear round artifacts, ordered round
+  barriers and the exact Round-2-question to Round-3-answer binding before the PM can finish.
+  Same-content retries are idempotent; conflicting round replays are rejected.
+
+## Package acceptance
+
+The release package check creates a physical npm tarball with lifecycle scripts disabled,
+installs it offline into a temporary prefix, starts that installed MCP server, and checks all
+four selector locales, exactly 31 MCP tools, exactly 26 catalog seats, one stable-ID
+selection, one receipt consumption and replay rejection. Full source, generated-pack and
+installed-tarball checks remain mandatory.
+
+## Runtime boundary
+
+- `full_v2` remains bounded queue-to-terminal at 1,800,000 ms for plugin-managed headless
+  execution. A deadline failure is persisted as incomplete; it is not a completeness promise.
+- Each selected physical v3 method still receives an isolated explanation worker only after
+  its deterministic stance is frozen. These are provisional project-derived method seats,
+  not the named people's statements, endorsements or current views.
+- Build channel: `solo_test`.
+- `production_eligible=false`.
+- `method_model_eligible=false`.
+- Physical provisional packs: 26.
+- Operational seats: 0.
+- Validated `method_model` seats: 0.
+- Formal GA remains fail-closed.