@v587d/capital-generation 2.7.7 → 2.7.9

package/selected-skills/financeskills/skills/wacc-computation/references/capm-basics.md

@@ -0,0 +1,24 @@
+# CAPM Basics
+
+## The Model
+`Re = Rf + β × ERP (+ size premium + country risk premium, if applicable)`
+
+- **Rf (Risk-Free Rate)**: Yield on default-free government bonds matching the cash flow horizon. Standard: 10-year Treasury (USD) or 10-year FGN bond (NGN valuations, with care — embed inflation differential).
+- **β (Beta)**: Sensitivity of the stock's returns to market returns. β > 1 = more volatile than market.
+- **ERP (Equity Risk Premium)**: Expected market return minus Rf. Common practice: 4.5%–6.0% mature-market ERP (Damodaran's updates are the standard citation).
+
+## Adjustments
+- **Size premium**: Add 1%–3% for small caps (Duff & Phelps/Kroll size deciles).
+- **Country risk premium (CRP)**: For emerging markets, add CRP = sovereign default spread × (σ_equity / σ_bond). Apply fully or scaled by the firm's revenue exposure (lambda approach).
+- **Currency consistency**: Match Rf, ERP, and cash flow currency. Never mix a USD risk-free rate with NGN cash flows without adjusting for inflation differential.
+
+## Common Errors
+1. Using a short-term T-bill rate for long-horizon valuation.
+2. Using raw regression beta without checking statistical significance (low R² → prefer industry beta).
+3. Double-counting country risk in both the discount rate and cash flow haircuts.
+4. Applying historical ERP over too short a window.
+
+## When CAPM Breaks Down
+- Private companies: no observable beta → unlever/relever industry comparables (see beta-math.md).
+- Thinly traded stocks: betas are unreliable → use sector betas.
+- Multi-business firms: compute divisional betas from pure-play comparables.

package/selected-skills/financeskills/skills/working-capital-analysis/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - working-capital-analysis
+
+## Ask
+
+> Revenue 7.3B/year, COGS 5.1B/year. AR 1.2B, inventory 900M, AP 700M. Compute the CCC and tell me what 10 days of DSO improvement is worth.
+
+## What a correct response contains
+
+DSO = 60 days, DIO = 64.4 days, DPO = 50.1 days, CCC = ~74.3 days. One day of revenue = 20M, so 10 DSO days = ~200M cash release.
+
+## File-driven variant
+
+With fixture(s) `evals/files/wc_balances.csv`:
+
+> From the attached balances (evals/files/wc_balances.csv), compute DSO, DIO, DPO, the cash conversion cycle, and the working-capital funding need it implies. Quantify the cash freed by cutting DSO by 10 days.
+
+Expected: DSO 60.0, DIO 77.8, DPO 53.7; CCC 84.1 days; funding need $13,278,279; 10 fewer DSO days frees ~$1,578,082.
+
+## Compute, don't estimate
+
+All figures above come from [`scripts/calculate.py`](./scripts/calculate.py) - import its functions rather than doing arithmetic in prose.

package/selected-skills/financeskills/skills/working-capital-analysis/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: working-capital-analysis
+description: When the user wants to analyze or optimize working capital — receivables, payables, inventory, and the cash conversion cycle. Also use when the user mentions "DSO," "DPO," "DIO," "cash conversion cycle," "cash tied up," "AR aging," "payment terms," "working capital peg," or "free up cash."
+metadata:
+  version: 1.0.0
+---
+
+# Working Capital Analysis
+
+You are a Working Capital Manager. Your goal is to quantify how much cash is tied up in the operating cycle, find where it's stuck, and free it without damaging operations or supplier/customer relationships.
+
+## Initial Assessment
+
+1. **Data Set**
+   - Monthly balances (AR, inventory, AP, other WC items) for ≥ 24 months — month-ends hide intra-month peaks; get weekly if financing is tight.
+   - Revenue and COGS by month; AR/AP agings; top-10 customer and supplier terms.
+
+2. **Context**
+   - Seasonality pattern, growth rate (growth consumes WC mechanically), any deal context (M&A working capital peg) or covenant pressure.
+
+---
+
+## Analysis Framework
+
+### Core Metrics
+- `DSO = AR / Revenue × 365` (use the countback method for seasonal businesses — simple DSO lies when sales swing)
+- `DIO = Inventory / COGS × 365`
+- `DPO = AP / COGS × 365`
+- `CCC = DSO + DIO − DPO`; `Cash impact of 1 day = annual revenue (or COGS) / 365`
+
+### Benchmark & Decompose
+Compare against sector peers and own history. Decompose every deterioration: volume vs. terms vs. discipline:
+- DSO up → mix shift to slower payers? terms creep? billing delays? disputes? collection slack? (aging waterfall answers this)
+- DIO up → safety-stock policy, slow-moving build (inventory-costing matrix), purchasing ahead of price increases, demand miss?
+- DPO down → early payments without discount capture? supplier term renegotiations lost? (Check: paying EARLY with no discount is free lending.)
+
+### Improvement Levers (ranked by speed)
+1. Billing hygiene: invoice same-day on delivery; e-invoicing; dispute root-cause kill list.
+2. Collections cadence: dunning calendar, credit holds, collector portfolios with targets.
+3. Terms governance: standard terms by segment, exception approval matrix, term-vs-price trade explicit.
+4. Payables: pay ON terms (not before), capture early-pay discounts only when discount APR > cost of funds: `APR = discount%/(1−discount%) × 365/(full term − discount term)`.
+5. Inventory: SKU-level service-vs-stock optimization, supplier lead-time programs, consignment.
+6. Structural: receivables financing/factoring, supply chain finance, dynamic discounting (cost these honestly).
+
+---
+
+## Technical Analysis Steps
+
+1. **Compute with code**: monthly metric trends, countback DSO, peak-vs-average WC, cash release quantification per lever (`days improvement × daily revenue/COGS`).
+2. **Aging quality analysis**: AR aging migration matrix month-over-month (which buckets feed 90+?); concentration of overdue in named accounts.
+3. **Seasonality-adjusted target**: set targets vs. same-month prior year; an absolute target across a seasonal year guarantees a fake Q-end scramble.
+
+---
+
+## Output Format
+
+### Working Capital Review
+
+**Dashboard**: CCC trend, component days, cash tied up vs. benchmark ("X days above peer median = ₦Y trapped").
+
+**Diagnosis**: decomposition of each component's movement with evidence.
+
+**Opportunity Sizing**: lever-by-lever cash release estimate with implementation difficulty.
+
+**Action Plan**: owner, lever, target days, timeline, and the operational risk of each move.
+
+---
+
+## Scripts
+- [calculate.py](./scripts/calculate.py): Deterministic functions for this skill's core computations. Run `python3 scripts/calculate.py` to self-test; import the functions instead of doing mental math.
+
+---
+
+## References
+- [WC Metrics Cookbook](./references/wc-metrics.md): Countback DSO, aging migration analysis, and the discount-APR decision rule.
+
+---
+
+## Related Skills
+- **treasury-management**: WC drives the cash forecast.
+- **financial-analysis**: Ratio context for the balance sheet.
+- **inventory-costing**: The valuation behind DIO.
+- **predictive-burn-rate**: For startups, WC timing is the collections curve.

package/selected-skills/financeskills/skills/working-capital-analysis/references/wc-metrics.md

@@ -0,0 +1,30 @@
+# Working Capital Metrics Cookbook
+
+## Countback DSO (use when sales are seasonal — always, really)
+Walk backwards through monthly sales until AR is exhausted:
+AR = 950; sales: Mar 400, Feb 380, Jan 350.
+- Mar covers 400 (31 days), remaining 550; Feb covers 380 (28 days), remaining 170; Jan: 170/350 × 31 = 15 days.
+- **Countback DSO = 31 + 28 + 15 = 74 days.** Simple DSO (950/avg monthly × 30) would misstate this badly after a strong quarter.
+
+## Aging Migration Matrix
+Track each bucket's flow month-over-month:
+| From \ To | Current | 1–30 | 31–60 | 61–90 | 90+ | Collected |
+|---|---|---|---|---|---|---|
+| Current | — | 22% | — | — | — | 78% |
+| 1–30 | — | — | 35% | — | — | 65% |
+| 31–60 | — | — | — | 48% | — | 52% |
+| 61–90 | — | — | — | — | 60% | 40% |
+Roll rates rising = collections discipline slipping BEFORE headline DSO moves. The 61–90 → 90+ roll rate is your bad-debt early warning and feeds the ECL provision matrix.
+
+## Early-Payment Discount APR Rule
+"2/10 net 45": `APR = 0.02/0.98 × 365/35 = 21.3%`.
+Take the discount if 21.3% > your marginal cost of funds; otherwise pay day 45. Build the table for every supplier's standard terms once — most teams leave easy money on one side or the other.
+
+## Peak vs. Average Working Capital
+Month-end WC understates the intra-month peak (payroll dates, VAT/tax payment days, inventory builds before sales spikes). For facility sizing: estimate peak = month-end + known intra-month swings; for M&A pegs: use a 12-month average to neutralize seasonality and define every account in the peg schedule explicitly (cash-free debt-free fights are won in the definitions).
+
+## Growth's WC Tax
+`ΔWC ≈ (CCC/365) × Δrevenue` (revenue-margin adjusted). A business at CCC 90 days growing revenue by 1B needs ~250M of new cash just to stand still — surface this in every growth plan review.
+
+## Quarter-End Window Dressing Tells
+DPO spikes every quarter-end then normalizes; receivables factored in the last week; inventory cut by delaying receipts. Use intra-period averages to see through it — and don't build the company's own targets in a way that incentivizes the same games.

package/selected-skills/quant-agent-skills/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerry Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/selected-skills/quant-agent-skills/UPSTREAM.md

@@ -0,0 +1,111 @@
+# Upstream Record
+
+- Project: Quant Agent Skills（三颗**自述为编排器**的量化研究 skill：`concept-research` 概念/题材、
+  `industry-research` 行业、`stock-research` 个股；A 股 / 港股 / 美股三市场分册 + A/H 与 ADR/HK 两条 overlay）
+- Repository: https://github.com/Howard-Jerry/quant-agent-skills
+- Upstream commit: `03677d216320f7f80ebf1f4d6d3106d41f72d333`（main，2026-08-05 20:27 +0800，作者 Jerry Wang）
+  - **全仓五次提交，全部落在 2026-08-05 同一天**（`f65c549` v1.0.0 → `03677d2` examples）。无 release、无 tag、无 CI。
+  - 上游 README 与 `docs/adaptation-guide.md` 自己写明：正文来自作者的**本地私有 SSoT**，经
+    `scripts/publish.sh` 同步发布，数据层（`collect-data`、候选队列）要到 **v1.1 才开源**；
+    贡献约定还规定"不要直接改 skill 正文再提交 PR"。frontmatter 里 `stock-research` 自报
+    `version: 2.46.0` —— 那个版本号是私有系统的历史，不代表公开版的成熟度。
+- License: MIT；`LICENSE` 为上游原件（`Copyright (c) 2026 Jerry Wang`），未改写。
+  **MIT 没有 Apache-2.0 第 4(b) 条那份"被改文件要带显著声明"的义务**，所以本颗不新增声明行
+  （与 `claude-for-financial-services-cn` 那一颗的区别正在这里，不是遗漏）。
+  上游 README 另带一句免责：仅供研究与教育用途、不构成投资建议、仓库不含任何实盘持仓数据。
+- Imported content: 所钉 commit 的完整文件树（三颗 skill 目录、`docs/`、`examples/`、`scripts/`、
+  `template/`、`README.md`、`CHANGELOG.md`、`LICENSE`），约 233 KB，**随 git 保留供复核**。
+  **随包发布的只有**：`LICENSE`、本文件，以及 `skills/cross-market-listing-choice/`
+  （一颗我们自持的入口 + 两份逐字复制的上游口径文件）。排除口径与理由写在快照自己的 `.npmignore`。
+
+## Local modifications（四类，逐条可复核；判据见 `docs/dev/selected-skills.md` §8.6）
+
+1. **新建一颗本仓自持的入口 skill** `skills/cross-market-listing-choice/SKILL.md`。
+   这不是上游正文的改写，而是本仓第一次在外部快照里放一颗自己写的正文——原因是一条结构事实：
+   provider 只把 `<skills 根>/<name>/SKILL.md` 认作可发现单位，而上游那三颗都不能进 catalog
+   （判断见下节），它们携带的两份**跨市场选线口径**因此没有可挂载的运行时入口。
+   入口正文全部由本仓撰写，口径来源只有那两份 overlay 文件与宿主既有纪律（委派取数、
+   不用记忆回填、不承诺收益、不代下单），没有从上游编排器里搬任何一句指令。
+2. **套了一层 `skills/`。** 上游把三颗 skill 直接放在**仓库根**，provider 的 `customSkillDirs`
+   与五处反查都按 `<repo>/<skillsDir>/<name>/SKILL.md` 走（peter-lynch 是同一类先例）。
+   `SELECTED_SKILL_SKILL_DIRS` 因此填 `'skills'`。
+3. **两份 `references/` 是逐字复制，不是移动**：`ah-overlay.md`、`adr-hk-overlay.md` 的原件仍住在
+   `stock-research/references/overlays/`（随 git 保留、不进发布包）。副本与上游**逐字节相同**，核对方式：
+   ```text
+   cmp skills/cross-market-listing-choice/references/ah-overlay.md \
+       <上游 commit>/stock-research/references/overlays/ah-overlay.md
+   ```
+   挑这两份（而不是 `markets/a-share.md` 那族）的唯一判据是**零执行面**：实测两份 overlay 正文
+   只含 ```text 围栏、零跨文件相对链接、零 `{{QUANT_ROOT}}` / `scripts/` / `*.py` / `collect-data`
+   一类私有栈引用，闸门 26 条模式零命中。`markets/a-share.md` 那份虽然 0 模式命中，但里面有
+   `PYTHONPATH={{QUANT_ROOT}} python data_platform/research_report_collector.py …` 这样的命令块，
+   指向公开版根本不附带的脚本——按第 4 条它要么整段删掉（就成了改上游正文），要么原样发出去
+   （就成了教 Agent 跑一条不存在的命令）。两条都不做，所以它不进包。
+4. **删除上游的 `.gitignore`**（只带 `.DS_Store` 与 `.env` 两条）。它会在本仓继续生效，
+   而 git 在被排除的父目录之下无法再 include（§8.6 那条实测教训）。
+
+**上游三颗正文一字未改**：不进 catalog 的正文不动也不扫（§8.6 开头那句），它们随 git 完整保留。
+
+## 收录判断：三颗编排器为什么一颗都不进 catalog
+
+按第 1、4、5、6 条逐条实测，不是印象：
+
+- **第 6 条（接管会话路由）**：三颗的 `description` 自报"编排器 / orchestrator"，正文是 Conductor
+  按步骤加载 `steps/*.skill.md`、并行派生 5–6 个 agent 再做 Debate 裁决——与本插件的角色路由正面冲突
+  （`china-stock-research-orchestrator`、InvestSkill 的 `full-report`、trading-skills 的四颗是同一类）。
+- **第 4 条（执行面）**：三颗都声明 `allowed-tools: Bash, Read, Write, Edit, EnterWorktree, ExitWorktree`
+  （后两个是 Claude Code 专属，DSH 运行时没有）。更硬的一条是**它们指挥的东西不在仓里**：
+  三颗 `SKILL.md` 点名的本地路径实测 **10 / 32 / 16 个，公开版一个都不存在**（`trade_history.json`、
+  `portfolio_state.json`、`research_verdicts.json`、`scripts/generate_bridge.py`、
+  `auto_research/quality_gate_check.py`、`sleeve/concept_heat.py`、`scripts/concept_radar.py` 等）。
+  把这种正文发给使用者，得到的是"教 Agent 去撞一堵墙"。
+- **第 1 条（第二条取数通道）**：`stock-research/steps/02-data-collection.skill.md` 写着
+  "**所有 DB 和 API 数据采集必须通过 `collect-data` skill 完成，禁止绕过 collect-data 直接调 API**"，
+  下面整张表是 Tushare / AkShare / yfinance / FRED / 东财 ReportAPI → 本地 SQLite + FTS5。
+  本插件的取数入口只有委派一个（§1.1），且原始 rows 永不出工具层。
+- **第 5 条 + `AGENTS.md` §7**：`04-output-delivery` 与 `references/output-contract.md` 要求产出
+  **五文件包**（`README.md` / `深度研究.md` / `财务数据.md` / `研报索引.md` / `跟踪框架.md`）
+  加一堆机器可读文件与 "Vault SHA 同步"。报告交付链路 2026-09-17 已整条删除、禁止以任何形式恢复。
+- **闸门实测**：全仓 51 份 `.md` 命中 **132 处**，分布极不均匀——三颗 `SKILL.md` 只有 **1 处**、
+  `steps/*` **109 处**、`agents/*` 9 处、我们真正取用的那族纯方法论 **1 处**（就是 `us-equity.md`
+  里的 AkShare 一词，而它不进包）、`detailed-workflows.md` 10 处。命中族是
+  71 个 ```python 围栏、40 个 `get_*(` 伪工具调用、17 个 AkShare、1 个 `ak.stock_news_em(`、1 个慧博。
+  **注意"1 处"不等于干净**：`python auto_research/quality_gate_check.py <research_dir>` 这类指令
+  现有 26 条模式一条都不认（第 10 条只认 `node|bash scripts/`）——这是"违规形状搬家"的又一次重演。
+- **还有一个架构级不兼容，值得单独记**：它整套结论都建立在**持有者的成交账本**上
+  （`Ledger reality`、`BLOCKED_LEDGER_MISSING_TRADE`、`current_new_money_pct`）。本插件从不持有
+  使用者的账本，只有自选股（观察清单），所以凡依赖账本的规则都落不了地。
+  `cross-market-listing-choice` 的正文因此明写"没有使用者的成交账本"这一条限制。
+
+## 已知未收、留给后续轮次的东西
+
+这几条按 catalog 现算的 67 颗 / 133 份 `.md` 实测是**空白**，且质地都好，但它们全部住在
+不能进 catalog 的编排器正文里，要接必须另起一轮重写：
+
+- **预期差闸门**：`delta_class=BEAT|IN_LINE|MISS|AMBIGUOUS` + "**公告披露不是叙事加速的充分条件**，
+  `IN_LINE` 不得直接升级 L3 / 龙头排序 / 入场线 / 仓位 / trigger，`BEAT` 也只能触发进一步验证"
+  （`concept-research/SKILL.md:58`、`industry-research/SKILL.md:52` 各一种措辞）。
+- **概念/题材叙事生命周期**：形成 → 加速 → 扩散 → 退潮 + 真龙/假龙（有业绩兑现 vs 纯叙事）。
+  本插件**数据面已经就绪**（`index_catalog` 概念板块目录、`index_constituents`、
+  `eastmoney_sector_rotation`、`eastmoney_cashflow_rotation`），缺的只是方法论面。
+- **check-first**：研究同一只票之前先读已有结论，并让使用者在"增量刷新 / 重做 / 只读复核"里选。
+- **境内券商评级结构性偏多**（"rating count is not a bullish thesis"）与
+  **A 股新股首日无涨跌幅 5 日**那一条（`markets/a-share.md`，含锁定期阶梯与招股书回退路径）。
+
+顺带一条数据面线索（不是 skill 问题）：它的 `report_rc` 对应 Tushare 的券商研报预测条目
+（前瞻 EPS / 目标价 / **上调下调方向**）。本插件的结构化面没有这一族，唯一的一致预期是
+`web_retriever` 的 `ths_eps_forecast`（机构数 / 最小 / 均值 / 最大 / 行业平均，且已带
+"机构数 <3 须一并披露"的纪律）。要不要补第二个来源，走 §10 数据源验收纪律另开。
+
+- Maintenance snapshot (checked 2026-10-13): 2 星、五次提交全在同一天、之后 70 天无提交、
+  0 issue、单人仓库，作者已声明数据层要到 v1.1 才开源。因此 catalog 标 `watchlist`——
+  是**维护薄**，不是那两份口径的内容缺陷。
+- Packaging: `.npmignore` 用七条目录规则 + 两条文件规则挡掉三颗编排器与上游工程材料；
+  `package.json` 的 `files` 登记 `selected-skills/quant-agent-skills`。
+  `test/packaging.test.mjs` 从 catalog 反查发布清单里的 `SKILL.md` / `LICENSE` / `UPSTREAM.md`，
+  并逐条反查 `.npmignore` 确实生效（目录与文件名两类都问）。
+- Runtime status: `watchlist` / 默认关闭。使用者在「插件」→ Capital Generation →「精选 Skills」
+  打开后，对之后的 Capital 会话可见；子 Agent 不继承。上游随 git 保留的脚本与编排器正文
+  **从不执行、也从不被 provider 读取**（skills 根里没有它们）。
+- Review status: 2026-11-15 复查上游、许可证与维护状态。届时若上游 v1.1 真的放出数据层，
+  重读上面"已知未收"那四条的可行性；不要在没有账本能力的前提下把它的 closeout 契约搬过来。

package/selected-skills/quant-agent-skills/skills/cross-market-listing-choice/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: cross-market-listing-choice
+description: 同一家公司在多个市场各有上市线（A+H 双上市、中概股的美股 ADR 与港股两条线）时，如何在**不重做公司研究**的前提下选一条来持有、加仓或观察：溢价与币种股息税、流动性与通道、披露文件路径。当且仅当问题问的是"同一家公司选哪条线"时使用；单一上市线的个股研究、比较两家公司、问公司本身好不好——都不走这颗。
+---
+
+# 跨市场选线（同一公司多条上市线）
+
+> 口径出处：`references/ah-overlay.md` 与 `references/adr-hk-overlay.md`，逐字取自上游
+> [Howard-Jerry/quant-agent-skills](https://github.com/Howard-Jerry/quant-agent-skills)
+> （MIT，commit `03677d2`）。那颗快照的三颗正文是自述的编排器、不进可选清单，随包只带这两份
+> 零执行面的口径文件；为什么这么切、改了什么，见本快照根的 `UPSTREAM.md`。
+
+## 什么时候用，什么时候不用
+
+用：公司结论已经有了（或本次不打算重做），剩下的问题是**这次动哪一条线**——A 股还是 H 股、
+ADR 还是港股、已持有的那条线要不要换成另一条。
+
+不用：只有一条上市线的公司；比较两家不同公司；问"这家公司值不值得研究"。那些是本插件
+其他研究路径的事，这颗一行都不接。**它不重做公司研究，只做选线。**
+
+## 一条铁律
+
+**公司层面只研究一次。** A 与 H、ADR 与港股，是同一家公司的两条线：现金流、竞争力、资产负债表
+**完全相同**，不同的只有执行、价差、税、流动性、货币和你能不能买到。
+
+由此得到两条禁止：
+
+- **不得因为一条线更便宜，就上调公司层面的结论。** 折价是选线理由，不是"这家公司更值得拥有"的理由。
+- **不得让包装层的便宜，盖掉公司层面缺失的证据。** 公司研究没做完，就先没有选线可言。
+
+这两句是这颗的核心，其余都是把它们变成可检查动作的细节。
+
+## 要拿的东西（一律走委派，本插件从不让分析角色自己伸手取数）
+
+向宿主的数据面要，一次把三项写全，缺哪一项就点名哪一项并停止依赖它的判断：
+
+1. **两条线在同一 as-of 交易日的收盘价**。币种分开写清楚：A 股那条是人民币，港股那条是港元，
+   ADR 是美元。**不许拿实时快照与历史收盘混算**——溢价是"同一天两个价格的比"。
+2. **同一天的汇率**（CNY 每 HKD，或 USD 每 HKD，按你对比的两条线取）。汇率取不到就是取不到：
+   本插件的汇率条目按次消耗上游积分，凭据缺失、限流或后端报错一律不重试，也不许用记忆里的
+   "大概 0.92"补一个数进去。
+3. **窗口是否干净**：两条线各自最近的拆股、送转、供股、大股东减持、回购注销有没有落在
+   你取的那段价格里。任一窗口被公司行动污染，就换到干净的后续窗口再比。
+
+股息代扣税、通道可用性（港股通 / 直接开户 / 券商能不能买）这类**规则性**事实会改，
+不向数据面要，按 `capital-web-protocol` 委派检索通道，把要核的问题、现行规则和时点写进 brief。
+
+## 溢价怎么算
+
+把算式写进答复里，让读者能复核——不要只给一个百分比。
+
+```text
+A/H 溢价 = (A_price_cny / fx_cny_per_hkd) / h_price_hkd - 1
+ADR/HK 平价 = (adr_price_usd / adr_ratio) / (hk_price_hkd * fx_hkd_per_usd) - 1
+```
+
+- `fx_cny_per_hkd` 是**一港元合多少人民币**，方向写反等于把溢价倒过来。
+- ADR 那条必须先除以 `adr_ratio`（一份 ADR 对应几股普通股），比例随公司行动变过就要重新确认。
+- 两个式子用的都必须是同一个 as-of 日的收盘与同一天汇率；日期不一致就分别标注并说明差距有多大。
+- 派生算术量大就交给宿主数据侧（委派 `data_junior`），少量数字在答复里把算式摊开即可。
+  本插件的分析角色不自己跑脚本。
+
+## 输出形状
+
+```text
+公司结论：<沿用已完成的那次研究，不在这里重做>
+若触发行动，优先哪条线：<A / H / ADR / 不换>
+理由：<价差 / 币种与股息税 / 流动性 / 通道 / 披露路径>，各一句
+```
+
+三份理由各归各位，不许混成一段"综合来看"。**价差只是其中一条**：一条线折价 30% 但你的账户
+买不到，那它对这个人没有意义；港股通额度、停牌规则、涨跌停（A 侧有、港侧无）都属于通道与执行。
+
+## 各市场要单独看的点
+
+- **A/H**：A 侧有涨跌停与 T+1，H 侧没有；H 侧还要看港股通通道与股息代扣。具体口径见
+  `references/ah-overlay.md`。
+- **ADR/HK**：ADR 是**存托凭证不是股票**——要看换算比例、能不能跨市场转托管（fungibility）、
+  退市与监管风险、以及**披露文件路径不同**：美国本土公司走 `10-K/10-Q/8-K`，外国私人发行人走
+  `20-F/6-K`。一条线的公告在另一条线的检索面里可能根本不存在，这是**市场边界，不是数据缺口**；
+  别把"这条线查不到"写成"这家公司没披露"。具体见 `references/adr-hk-overlay.md`。
+
+## 出处块
+
+分析结束时按本插件的统一形状交代出处，把每一项证据的来路写全：
+
+```text
+Data & Sources
+  - <事实或数字>：来源=<Dataset 引用 / 披露文件名 / 网页标题与日期>
+    as-of=<YYYY-MM-DD>
+    Retrieval:  <delegated retrieval | web/tool retrieval | pasted by user>
+```
+
+`Retrieval` 只能是这三档之一。**"我记得大概是这个汇率"不是一档取数途径。**
+
+## 这颗做不到什么（先说清楚，别到时候编）
+
+- **本插件没有使用者的成交账本。** 这颗不持久化你的持仓、成本价与已实现盈亏。上文"已持有
+  的那条线要不要换"只能按你在对话里当场给出的信息回答，回答完就放下；也不要假装查过账户。
+- **没有现成的 A/H 溢价或 ADR 平价条目。** 溢价必须自己按两条线的收盘与当日汇率算出来，
+  这三项里任何一项取不到，就不要给溢价数字，只报告缺哪一项。
+- **不承诺收益，不预测价差收敛。** "A 比 H 贵 40%"是当天的事实，"所以 H 会涨"不是这颗的结论。
+  历史价差区间可以作为参照，但要写明它是参照、不是目标。
+- **不构成投资建议，也不代使用者下单。** 本插件不提供交易执行界面；最终动哪条线、动多少，
+  由使用者自己决定并自己执行。

package/selected-skills/quant-agent-skills/skills/cross-market-listing-choice/references/adr-hk-overlay.md

@@ -0,0 +1,45 @@
+# ADR / HK Overlay
+
+Use when the same company trades as a U.S. ADR and Hong Kong share, or when a
+U.S.-listed ADR has a related HK primary/secondary listing.
+
+## Principle
+
+Research the company once. The overlay chooses the better security wrapper for
+execution and risk control.
+
+## Required Checks
+
+- Alias coverage for ADR ticker, HK ticker, Chinese name, English name, and
+  historical names.
+- Share ratio:
+  - ADR-to-ordinary share conversion ratio;
+  - price parity after FX and ratio adjustment.
+- Currency:
+  - USD vs HKD;
+  - FX basis date.
+- Listing and regulatory risk:
+  - HFCAA/delisting risk if applicable;
+  - primary vs secondary listing status;
+  - fungibility and conversion constraints.
+- Liquidity and trading access:
+  - U.S. session vs HK session;
+  - spread and average daily value;
+  - available account/channel.
+- Filing path:
+  - U.S. domestic forms (`10-K/10-Q/8-K`) vs foreign private issuer forms
+    (`20-F/6-K`);
+  - company IR fallback when local SEC collector does not yet cover forms.
+
+## Output Rule
+
+Write:
+
+```text
+Company verdict: <WAIT/BUY/HOLD/...>
+Preferred security if action triggers: <ADR/HK/no-switch>
+Wrapper reason: <parity, liquidity, filing, regulatory, FX, channel>
+```
+
+Do not let wrapper cheapness override missing company-level evidence.
+

package/selected-skills/quant-agent-skills/skills/cross-market-listing-choice/references/ah-overlay.md

@@ -0,0 +1,44 @@
+# A/H Overlay
+
+Use when the same company has both A-share and H-share listings. This overlay
+answers which security is better for execution after the company thesis is
+already researched.
+
+## Principle
+
+Company-level research is done once. A vs H does not change the company's cash
+flows. It changes execution, valuation spread, tax, liquidity, currency, and
+access.
+
+## Required Checks
+
+- Alias coverage for A code, H code, Chinese name, English name, short names,
+  and common variants.
+- A/H premium:
+  - compute with consistent price dates;
+  - convert currency: `(A_price / FX_CNY_per_HKD) / H_price - 1`;
+  - use a clean post-split/post-corporate-action window when old data is
+    polluted.
+- Currency and dividend tax:
+  - CNY vs HKD basis;
+  - HK Stock Connect dividend withholding when relevant.
+- Liquidity and channel:
+  - A-share liquidity/limit-up-down/microstructure;
+  - HK liquidity, southbound access, borrow/short availability if relevant.
+- Portfolio reality:
+  - current held line;
+  - trade ledger currency and cost basis;
+  - whether switching lines is operationally possible.
+
+## Output Rule
+
+Write the overlay as:
+
+```text
+Company verdict: <WAIT/BUY/HOLD/...>
+Preferred listing if action triggers: <A/H/no-switch>
+Reason: <premium, currency, tax, liquidity, channel>
+```
+
+Never upgrade a weak company-level EV just because one line is cheaper.
+