alphacouncil-agent 0.5.5 → 0.8.0

package/docs/roadmap.md

@@ -0,0 +1,104 @@
+# Roadmap
+
+Where this plugin is going, and the reasoning that decides it. Dated entries, newest first.
+Anything here is a statement of intent, not a shipped feature. Shipped work lives in
+`CHANGELOG.md`.
+
+## The problem that shapes everything after 0.6.0
+
+A user asked why the master bench never appears in the report. Answering it surfaced a
+larger defect, and the larger defect is the one worth stating plainly:
+
+> Twenty-one masters are twenty-one prompt voices, not twenty-one independent sources.
+> They share a base model, a batch of evidence, a training corpus, a context bias, and
+> therefore a set of factual errors. "Twenty-one votes" is not twenty-one samples. It can
+> be one error repeated in twenty-one investing accents.
+
+This is correct, and the published literature is harsher than the summary above.
+
+- Contemporary LLM errors are **>60% correlated**, so naive ensembling has a non-zero
+  error floor. ([Minority Sentinel](https://arxiv.org/html/2606.29270v1))
+- Majority voting inherits its legitimacy from the **Condorcet Jury Theorem**, which
+  requires *independent* errors. Shared pretraining violates the premise outright.
+- When agents are handed **identical information**, deliberation does not raise collective
+  accuracy — they already agreed, and exchanging messages only hardens the shared prior.
+  ([Diverse Evidence, Better Forecasts](https://arxiv.org/html/2607.01661v1))
+- With identical inputs, debate forms a **martingale**: expected correctness does not
+  improve across rounds. Closed deliberation is a Markov chain whose mutual information
+  with the truth can only decrease.
+- The failure mode has a name — **the Deliberative Illusion**: factual attrition plus
+  stance homogenisation. ([arXiv 2606.03032](https://arxiv.org/pdf/2606.03032))
+- In roughly **one divergent case in four the minority is right**, so a majority rule
+  actively destroys the most valuable signal in the room.
+
+The plugin has been shipping the exact artifact this literature warns about: a tally.
+
+### What that means for how a run is reported
+
+A concurring bench is the *weakest* thing the council produces, not the strongest. The
+dissenting seat is the informative one. Any report that prints `6 avoid / 2 neutral /
+2 long` and lets the reader do arithmetic on it is selling correlated noise as consensus.
+
+## 0.7.0 — the bench becomes visible (prerequisite, not a feature)
+
+`markdown.mjs` contains zero references to `master`. Master opinions are recorded, gated
+for completeness, weighted in synthesis — and then rendered nowhere. A run can select ten
+lenses, pay for ten, pass every gate, and emit a report in which they are invisible.
+
+Folded into 0.8.0 rather than shipped alone: you cannot evaluate whether a persona rewrite
+worked while its output is unreadable.
+
+- Render master opinions to `master_<id>.md`, `all_agents.md`, and `artifact_index.md`.
+- Add a `master_bench` report section, required only when a bench was actually selected.
+- Make the analyst work log generate from packets instead of trusting the manager to retype
+  them, and make the gate check for substance rather than for the task name as a substring.
+- Stop returning the entire run state from every `record_*` call. Late in a long run a
+  single response reached ~240k characters, which is a context-exhaustion bug on any host
+  that keeps tool results in the transcript.
+
+## 0.8.0 — masters become methods, not accents
+
+The fix is architectural, and the reference implementation for it already exists in the
+open: in [`virattt/ai-hedge-fund`](https://github.com/virattt/ai-hedge-fund) the Buffett
+agent is not a prompt. It is a scoring function — ROE > 15%, debt/equity < 0.5, operating
+margin > 15%, owner earnings with maintenance capex at 85% of total capex, a two-stage DCF
+capped at 8%/4% with a 2.5% terminal and a 0.85 margin-of-safety multiplier. The model is
+called **after** `total_score` and `max_possible_score` already exist, and it writes prose
+about a verdict it did not choose.
+
+That is the whole idea: **differentiation lives in code, not in the prompt.** Two masters
+differ because they compute different functions over different inputs — not because one of
+them was told to sound like Omaha.
+
+Four layers per master, with the model confined to the last one:
+
+1. **Eligibility gate** — can this method evaluate this security at all? Deterministic.
+   Buffett facing a 20-F filer with 0/7 computable rules returns `out_of_scope` and never
+   reaches an LLM.
+2. **Scoring function** — named metrics, numeric thresholds, weights, provenance for every
+   threshold. Deterministic.
+3. **Evidence slice** — different masters read *different* evidence. This is the lever the
+   information-asymmetry paper identifies, and it is the only one that produces disagreement
+   from something other than tone.
+4. **Narrative** — the model explains a stance it cannot overturn.
+
+Reporting changes with it: the tally disappears, correlation is disclosed as a property of
+the run, and the minority report is promoted rather than buried.
+
+A new `council_diagnostics` tool measures whether any of this worked — self-consistency of
+one master across runs against pairwise agreement between masters. **If different masters
+agree with each other about as often as one master agrees with itself, the bench added no
+information, and the report must say so.** A feature that can prove itself decorative is
+worth more than one that cannot.
+
+Full plan: `docs/plans/0.8.0-master-models.md`.
+
+## Known limits that no version fixes
+
+- **Shared base model.** Per-master vendor routing narrows the correlation; it does not
+  make the seats independent, and it costs keys most users will not have.
+- **Thresholds are still human choices.** Determinism moves the uncertainty from the model
+  into the constants. The mitigation is provenance, not confidence.
+- **Some masters have thin public methodology.** There is far more verifiable Buffett than
+  verifiable Duan Yongping. Those rule sets will be smaller and labelled as such. Padding
+  them to look uniform would reintroduce exactly the invention this release exists to remove.

package/knowledge/masters/master_buffett/manifest.json

@@ -0,0 +1,209 @@
+{
+  "schema_version": 2,
+  "persona_id": "master_buffett",
+  "display_name": {
+    "en": "Buffett Method Model",
+    "zh": "巴菲特方法模型"
+  },
+  "kind": "operator_lens",
+
+  "admission": {
+    "propositions": 6,
+    "primary_sources": 4,
+    "decision_cases": 0,
+    "failure_cases": 1,
+    "vetoes": 2,
+    "counterfactuals": 0
+  },
+
+  "sources": [
+    {
+      "id": "buffett:S01",
+      "grade": "A",
+      "title": "Berkshire Hathaway 1987 Chairman's Letter",
+      "url": "https://www.berkshirehathaway.com/letters/1987.html",
+      "date": "1988-02-29",
+      "excerpt": "returns on equity ... without the aid of leverage"
+    },
+    {
+      "id": "buffett:S02",
+      "grade": "A",
+      "title": "Berkshire Hathaway 1986 Chairman's Letter, Appendix: owner earnings",
+      "url": "https://www.berkshirehathaway.com/letters/1986.html",
+      "date": "1987-02-27",
+      "excerpt": "reported earnings plus depreciation and amortization less capitalized expenditures required to maintain long-term competitive position"
+    },
+    {
+      "id": "buffett:S03",
+      "grade": "A",
+      "title": "Berkshire Hathaway 1996 Chairman's Letter, circle of competence",
+      "url": "https://www.berkshirehathaway.com/letters/1996.html",
+      "date": "1997-02-28",
+      "excerpt": "you don't have to be an expert on every company ... define your circle of competence"
+    },
+    {
+      "id": "buffett:S04",
+      "grade": "A",
+      "title": "Berkshire Hathaway 1989 Chairman's Letter, mistakes of the first twenty-five years",
+      "url": "https://www.berkshirehathaway.com/letters/1989.html",
+      "date": "1990-03-02",
+      "excerpt": "the most important lesson ... a good business at a fair price over a fair business at a good price"
+    }
+  ],
+
+  "doctrine": [
+    {
+      "rule_id": "buffett.circle_of_competence.01",
+      "claim": "Stop valuing a business whose model cannot be explained in a paragraph",
+      "scope": ["public_equity", "operating_business"],
+      "trigger": "business_model_explanation_failed",
+      "action": "out_of_scope",
+      "source_ids": ["buffett:S03"],
+      "confidence": "high",
+      "counterexamples": [],
+      "version": 1
+    },
+    {
+      "rule_id": "buffett.record_required.01",
+      "claim": "A long-run return-on-equity record is the entry requirement, not an optional extra; without the series there is no judgment to make",
+      "scope": ["public_equity"],
+      "trigger": "long_run_roe_series_unavailable",
+      "action": "out_of_scope",
+      "source_ids": ["buffett:S01"],
+      "confidence": "high",
+      "counterexamples": ["a recent spin-off with no standalone history may still be analysable from the parent's segment disclosure"],
+      "version": 1
+    },
+    {
+      "rule_id": "buffett.owner_earnings.01",
+      "claim": "Value the business on owner earnings, not reported earnings: reported earnings plus depreciation and amortization, less the capital expenditure required to hold competitive position",
+      "scope": ["public_equity"],
+      "trigger": "valuation_requested",
+      "action": "require_evidence",
+      "source_ids": ["buffett:S02"],
+      "confidence": "high",
+      "counterexamples": [],
+      "version": 1
+    },
+    {
+      "rule_id": "buffett.leverage.01",
+      "claim": "A high return on equity achieved with heavy leverage is not evidence of business quality",
+      "scope": ["public_equity"],
+      "trigger": "roe_high_with_high_debt",
+      "action": "veto",
+      "source_ids": ["buffett:S01"],
+      "confidence": "high",
+      "counterexamples": ["regulated utilities and banks carry structural leverage and are judged on other terms"],
+      "version": 1
+    },
+    {
+      "rule_id": "buffett.quality_over_price.01",
+      "claim": "Prefer a good business at a fair price to a fair business at a good price",
+      "scope": ["public_equity"],
+      "trigger": "cheapness_is_the_only_argument",
+      "action": "downweight",
+      "source_ids": ["buffett:S04"],
+      "confidence": "high",
+      "counterexamples": [],
+      "version": 1
+    },
+    {
+      "rule_id": "buffett.cash_conversion.01",
+      "claim": "Earnings that do not arrive as cash over a full cycle are a claim about accounting, not about a business",
+      "scope": ["public_equity"],
+      "trigger": "ocf_below_net_income_over_cycle",
+      "action": "downweight",
+      "source_ids": ["buffett:S02"],
+      "confidence": "medium",
+      "counterexamples": ["a fast-growing business funding working capital can run below for several years"],
+      "version": 1
+    }
+  ],
+
+  "research_policy": {
+    "priorities": ["moat_durability", "capital_allocation_record", "owner_earnings", "pricing_power"],
+    "must_recompute": ["owner_earnings", "roe_ex_leverage"],
+    "must_seek_disconfirming": ["accounting concern", "goodwill impairment", "serial restructuring", "management incentive misalignment"],
+    "evidence_slice": ["earnings_deep_dive", "insider_sec", "ib_event_analysis", "news_industry_management"]
+  },
+
+  "decision_policy": {
+    "eligibility": {
+      "requires": [
+        "screen.rules_computed >= 4",
+        "filer.structured_financials"
+      ],
+      "on_fail": "out_of_scope"
+    },
+    "scoring": {
+      "max_score": 12,
+      "rules": [
+        {
+          "id": "roe_10y",
+          "metric": "screen.metrics.roe_10y",
+          "op": ">=",
+          "value": 0.15,
+          "points": 3,
+          "provenance": "1987 letter (buffett:S01): sustained above-average return on equity without the aid of leverage"
+        },
+        {
+          "id": "debt_to_equity",
+          "metric": "screen.metrics.debt_to_equity",
+          "op": "<=",
+          "value": 0.5,
+          "points": 2,
+          "provenance": "1987 letter (buffett:S01): the ROE test is only meaningful unlevered, so leverage is capped rather than scored"
+        },
+        {
+          "id": "gross_margin_long_run",
+          "metric": "screen.metrics.gross_margin",
+          "op": ">=",
+          "value": 0.4,
+          "points": 2,
+          "provenance": "pricing power proxy; durable margin is the observable form of the moat in buffett:S04"
+        },
+        {
+          "id": "ocf_over_ni",
+          "metric": "screen.metrics.ocf_over_ni",
+          "op": ">=",
+          "value": 1,
+          "points": 3,
+          "provenance": "owner-earnings definition (buffett:S02): earnings only count once they arrive as cash"
+        },
+        {
+          "id": "dilution_5y",
+          "metric": "screen.metrics.dilution_5y",
+          "op": "<=",
+          "value": 0.05,
+          "points": 2,
+          "provenance": "capital allocation record; share count growth is the cost of every acquisition and grant"
+        }
+      ]
+    },
+    "stance_bands": [
+      { "min_ratio": 0.75, "stance": "constructive" },
+      { "min_ratio": 0.4, "stance": "cautious" },
+      { "min_ratio": 0, "stance": "opposed" }
+    ],
+    "vetoes": [
+      {
+        "id": "leveraged_roe",
+        "condition": "screen.metrics.debt_to_equity >= 2",
+        "source_ids": ["buffett:S01"]
+      },
+      {
+        "id": "cash_never_arrives",
+        "condition": "screen.metrics.ocf_over_ni <= 0.5",
+        "source_ids": ["buffett:S02"]
+      }
+    ]
+  },
+
+  "memory_policy": {
+    "horizon_days": 365,
+    "belief_decay_days": 540,
+    "leak_rule": "public_at <= as_of AND memory_created_at <= as_of"
+  },
+
+  "tools": ["screen_ticker", "get_news"]
+}

package/knowledge/masters/master_duan_yongping/manifest.json

@@ -0,0 +1,201 @@
+{
+  "schema_version": 2,
+  "persona_id": "master_duan_yongping",
+  "display_name": {
+    "en": "Duan Yongping Method Model",
+    "zh": "段永平方法模型"
+  },
+  "kind": "operator_lens",
+
+  "admission": {
+    "propositions": 6,
+    "primary_sources": 3,
+    "decision_cases": 0,
+    "failure_cases": 2,
+    "vetoes": 2,
+    "counterfactuals": 0
+  },
+
+  "sources": [
+    {
+      "id": "duan:S01",
+      "grade": "A",
+      "title": "段永平雪球账号「大道无形我有型」问答合集（本人署名发布）",
+      "url": "https://xueqiu.com/u/1247347556",
+      "date": "2010-2026",
+      "excerpt": "本分；不懂不做；做对的事情，把事情做对"
+    },
+    {
+      "id": "duan:S02",
+      "grade": "A",
+      "title": "段永平网易博客（本人署名，早期方法论文章）",
+      "url": "https://blog.163.com/duan_yp/",
+      "date": "2006-2012",
+      "excerpt": "商业模式、企业文化、合理价格"
+    },
+    {
+      "id": "duan:S03",
+      "grade": "B",
+      "title": "段永平浙江大学交流实录（可核验完整问答记录）",
+      "url": "https://www.zju.edu.cn/",
+      "date": "2018-2021",
+      "excerpt": "敢为天下后，后中争先；停止做不对的事情"
+    }
+  ],
+
+  "doctrine": [
+    {
+      "rule_id": "duan.bu_dong_bu_zuo.01",
+      "claim": "不懂不做：无法说清这门生意如何长期赚钱时，不进入，且不因为便宜而破例",
+      "scope": ["public_equity", "operating_business"],
+      "trigger": "business_model_not_explainable",
+      "action": "out_of_scope",
+      "source_ids": ["duan:S01"],
+      "confidence": "high",
+      "counterexamples": [],
+      "version": 1
+    },
+    {
+      "rule_id": "duan.business_model_first.01",
+      "claim": "商业模式优先于财务指标：先判断生意本身是否好，再谈价格",
+      "scope": ["public_equity"],
+      "trigger": "valuation_requested",
+      "action": "require_evidence",
+      "source_ids": ["duan:S02"],
+      "confidence": "high",
+      "counterexamples": [],
+      "version": 1
+    },
+    {
+      "rule_id": "duan.culture.01",
+      "claim": "企业文化（本分）是长期结果的决定项；管理层言行不一时，财务数字不足以补偿",
+      "scope": ["public_equity"],
+      "trigger": "management_behaviour_inconsistent",
+      "action": "veto",
+      "source_ids": ["duan:S01", "duan:S02"],
+      "confidence": "high",
+      "counterexamples": [],
+      "version": 1
+    },
+    {
+      "rule_id": "duan.stop_doing_list.01",
+      "claim": "停止做不对的事情，比多做正确的事情更重要；默认不行动",
+      "scope": ["public_equity", "portfolio"],
+      "trigger": "no_clear_edge",
+      "action": "downweight",
+      "source_ids": ["duan:S03"],
+      "confidence": "high",
+      "counterexamples": ["已充分理解且价格明显低于价值时不适用"],
+      "version": 1
+    },
+    {
+      "rule_id": "duan.opportunity_cost.01",
+      "claim": "任何买入都要与当前最好的已持有标的比较；比不过就不买",
+      "scope": ["portfolio"],
+      "trigger": "candidate_vs_incumbent",
+      "action": "downweight",
+      "source_ids": ["duan:S01"],
+      "confidence": "high",
+      "counterexamples": [],
+      "version": 1
+    },
+    {
+      "rule_id": "duan.user_value.01",
+      "claim": "用户价值是收入的来源；产品与用户证据先于报表证据",
+      "scope": ["public_equity"],
+      "trigger": "revenue_quality_assessment",
+      "action": "require_evidence",
+      "source_ids": ["duan:S02"],
+      "confidence": "medium",
+      "counterexamples": ["纯授权型业务的用户证据链较弱，需改用合约证据"],
+      "version": 1
+    }
+  ],
+
+  "research_policy": {
+    "priorities": ["business_model_clarity", "corporate_culture", "user_value", "opportunity_cost"],
+    "must_recompute": ["opportunity_cost_vs_incumbent"],
+    "must_seek_disconfirming": ["management promise versus action", "culture events", "user complaints", "channel stuffing"],
+    "evidence_slice": ["news_industry_management", "earnings_deep_dive", "insider_sec"]
+  },
+
+  "decision_policy": {
+    "eligibility": {
+      "requires": [
+        "business_model.explainable",
+        "culture.evidence_available"
+      ],
+      "on_fail": "out_of_scope"
+    },
+    "scoring": {
+      "max_score": 12,
+      "rules": [
+        {
+          "id": "business_model_simplicity",
+          "metric": "business_model.simplicity_score",
+          "op": ">=",
+          "value": 0.6,
+          "points": 3,
+          "provenance": "duan:S02 商业模式优先；说不清就不做，简单是可判断性的前提"
+        },
+        {
+          "id": "culture_benfen",
+          "metric": "culture.benfen_score",
+          "op": ">=",
+          "value": 0.6,
+          "points": 3,
+          "provenance": "duan:S01 本分；文化是长期结果的决定项"
+        },
+        {
+          "id": "user_value",
+          "metric": "product.user_value_score",
+          "op": ">=",
+          "value": 0.6,
+          "points": 2,
+          "provenance": "duan:S02 用户价值是收入的来源"
+        },
+        {
+          "id": "beats_incumbent",
+          "metric": "portfolio.beats_best_incumbent",
+          "op": "==",
+          "value": true,
+          "points": 2,
+          "provenance": "duan:S01 机会成本；比不过手上最好的就不买"
+        },
+        {
+          "id": "net_cash",
+          "metric": "screen.metrics.net_cash_positive",
+          "op": "==",
+          "value": true,
+          "points": 2,
+          "provenance": "duan:S02 合理价格与安全性；净现金降低对时机的依赖"
+        }
+      ]
+    },
+    "stance_bands": [
+      { "min_ratio": 0.75, "stance": "constructive" },
+      { "min_ratio": 0.45, "stance": "cautious" },
+      { "min_ratio": 0, "stance": "opposed" }
+    ],
+    "vetoes": [
+      {
+        "id": "integrity_breach",
+        "condition": "culture.integrity_flag",
+        "source_ids": ["duan:S01", "duan:S02"]
+      },
+      {
+        "id": "model_not_explainable",
+        "condition": "!business_model.explainable",
+        "source_ids": ["duan:S01"]
+      }
+    ]
+  },
+
+  "memory_policy": {
+    "horizon_days": 730,
+    "belief_decay_days": 1095,
+    "leak_rule": "public_at <= as_of AND memory_created_at <= as_of"
+  },
+
+  "tools": ["get_news", "screen_ticker"]
+}