alphacouncil-agent 0.9.4 → 1.0.0

package/docs/releases/v1.0.0.md

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

package/docs/report-contract.md

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

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:3e3ba26efc5e2b26c1f7549c845af116b7a07b9b8814cb16bd0bbf633289d3eb",
+    "input_hash": "sha256:9127909a333bb31bf3bda341b3f975c47b99dc709ae602fd643cb8aca4373882",
     "path": "simulation-input.json"
   },
   "network_allowed": false,
   "production_effect": "none",
-  "result_hash": "sha256:00da168490d6f96bd98e05a69427686ed2b19b9a6e1c23033e004de3798df762",
+  "result_hash": "sha256:b6de9683451d9b4063cbab22561e335d6436637d20fb77baa4f5ad930e043994",
   "results": {
     "blocked_fail_closed_count": 0,
     "completion_status": "completed_machine_simulation",
     "decisions": [
       {
-        "anonymous_method_hash": "sha256:c617108770534f6c0299a134d0014838c4d9dc8a8e96496563e557063e6cfd25",
-        "deterministic_core_hash": "sha256:a67003279083423cab89962354372c6a19f16e5260579000816a8fcc39ed5a38",
-        "fact_pack_hash": "sha256:0adab0b69b1e8ba756deaeac3c457e044dd5a7195b1847893db0953772220e41",
-        "frozen_decision_hash": "sha256:ddfd120be4926ef3b400a07f8af44c277d170f4c8f48364579b5b21ae48fa661",
-        "native_state": "provisional_own_at_price",
-        "pack_hash": "sha256:acd69a6e493f5b1faa050d3266d12ed6d97a7e698daeba073727c085ff5c63dd",
+        "anonymous_method_hash": "sha256:ab1138811cd18a46315a4c7f840962dfe643e724c62e1343f35450e4826aac52",
+        "deterministic_core_hash": "sha256:1138841001cf2bf5b3f3faee980b23f36ac693b79cc7832fe90433948600464f",
+        "fact_pack_hash": "sha256:2887ff3b609b4d2d32b25ec1f81b7a46bea1b1cc1506d31582e6f8517591f907",
+        "frozen_decision_hash": "sha256:f758e6c2c6166fcd40ef2cb68dc80402f14c8d8097f90cce629ae7df3e652fde",
+        "native_state": "provisional_reject",
+        "pack_hash": "sha256:ddc7163f4e87ab93755fe95371029d811cedc273c14bdc273422eaa4dc370181",
         "persona_id": "master_buffett",
-        "policy_execution_hash": "sha256:5e853405b4dd96e4760f842c0726e26bf7f87e9e3cc79a6b90e3ceb58a2211a5",
-        "score_ratio": 1,
-        "stance": "cautious",
+        "policy_execution_hash": "sha256:e9f632cee5f5527bcfd7af58bfe34a4c085d48e5fe7efce6286b47483c25fd9b",
+        "score_ratio": 0.3333333333333333,
+        "stance": "opposed",
         "status": "executed",
-        "structured_decision_hash": "sha256:4dd09d873884782402697e0ac7ef70fc61ab76440f221274b7a16c13a1b66e3c"
+        "structured_decision_hash": "sha256:57a0f42891d0004baf89a7009aff6e17b504ebf8b8152ab288b54fe08438a4a7"
       }
     ],
     "deterministic_execution_count": 1,
@@ -54,7 +54,7 @@
     "verifier_checks": []
   },
   "reviewer_kind": "ai",
-  "run_artifact_hash": "sha256:01f7b32aea7e26f216d62f3d1123770e39defa026bb83f65dbb4475d572a7280",
+  "run_artifact_hash": "sha256:351606eac119186416b5d598c162b19151a89820c5abd0445b7413e66d77816d",
   "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:3e3ba26efc5e2b26c1f7549c845af116b7a07b9b8814cb16bd0bbf633289d3eb",
+    "input_hash": "sha256:9127909a333bb31bf3bda341b3f975c47b99dc709ae602fd643cb8aca4373882",
     "path": "simulation-input.json"
   },
   "network_allowed": false,
@@ -37,7 +37,7 @@
     "verifier_checks": []
   },
   "reviewer_kind": "ai",
-  "run_artifact_hash": "sha256:8e089c92d91ec2e790a3d253a539376c706c3d7a99a71dad249d41f213ac6de0",
+  "run_artifact_hash": "sha256:40b99e59216b8689cb696f62f33562545c686d890a637fd2daeba9339f0d3674",
   "run_id": "B",
   "schema_version": 1,
   "simulation_scope": "frozen-input control digest only; eight LLM analyst outputs are not simulated"

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

@@ -16,7 +16,7 @@
   "formal_h_satisfied": false,
   "human_reference": false,
   "input_binding": {
-    "input_hash": "sha256:3e3ba26efc5e2b26c1f7549c845af116b7a07b9b8814cb16bd0bbf633289d3eb",
+    "input_hash": "sha256:9127909a333bb31bf3bda341b3f975c47b99dc709ae602fd643cb8aca4373882",
     "path": "simulation-input.json"
   },
   "network_allowed": false,
@@ -37,7 +37,7 @@
     "verifier_checks": []
   },
   "reviewer_kind": "ai",
-  "run_artifact_hash": "sha256:cd7b259120c835df126e2e445e131a5d595e4efbd059c27d20a9f596390744d3",
+  "run_artifact_hash": "sha256:5158ac7a004d8a39a013ffed82ce15b851d4a7fbe921d8c0400c76e2a95f4756",
   "run_id": "C",
   "schema_version": 1,
   "simulation_scope": "prompt-catalog binding only; prompt-only LLM outputs are not simulated"