yf176 commited on
Commit
0887bee
·
1 Parent(s): 7e4b3af

docs: draft V8.0 routing and artifact ACL contracts

Browse files
Files changed (1) hide show
  1. docs/polyhedraV8.0.md +461 -0
docs/polyhedraV8.0.md ADDED
@@ -0,0 +1,461 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Polyhedra V8.0 - PRD (Structured Agent Collaboration)
2
+
3
+ > Discovery draft. Paper-trading only. No real capital. Not financial advice.
4
+ > V8.0 inherits the existing quant product behavior while replacing implicit
5
+ > agent sequencing and file conventions with explicit runtime contracts.
6
+
7
+ ---
8
+
9
+ ## Vision
10
+
11
+ V8.0 moves Polyhedra from a primarily linear chain of quant agents to
12
+ collaboration through the session folder. The collaboration model is governed
13
+ by three structured contracts:
14
+
15
+ 1. A Routing Table that declares agent dependencies and controls activation.
16
+ 2. A session-artifact ACL that controls which artifacts each agent may read,
17
+ write, edit, and list.
18
+ 3. Typed artifact schemas that define agent inputs and outputs.
19
+
20
+ The Routing Table is the workflow authority. The runtime evaluates it as a
21
+ dependency graph, but the PRD and UI present it as a table. An LLM performs
22
+ reasoning inside an activated agent, but it does not select the next workflow
23
+ agent.
24
+
25
+ ---
26
+
27
+ ## Inherited Product Contract
28
+
29
+ V8.0 preserves the existing quant product and its session-based YOLO behavior:
30
+
31
+ - The first YOLO run in a session creates a complete baseline.
32
+ - Later YOLO runs in the same session reuse prior context and focus on changes.
33
+ - RAG remains available and must obey the same artifact ACL as every agent.
34
+ - Finley remains the final user-facing output layer.
35
+ - The product remains paper-trading only.
36
+
37
+ V8.0 focuses only on quant agents. Academic and research agents are outside the
38
+ V8.0 product scope.
39
+
40
+ ---
41
+
42
+ ## Current Architecture Baseline
43
+
44
+ V8.0 starts from the current implementation rather than replacing the quant
45
+ product with a separate workflow.
46
+
47
+ - Every agent currently implements the common runtime call shape
48
+ `handle(mention, thread_context, research_state)` and returns an
49
+ `AgentResponse` envelope.
50
+ - Quant output models exist, but typed outputs are not populated and enforced
51
+ consistently across all agents.
52
+ - Most agent-to-agent inputs are markdown artifacts selected by filename
53
+ convention rather than validated typed artifact contracts.
54
+ - The coordinator injects a session-scoped `FileWriter` into each agent.
55
+ Agent code can currently read, write, and list session-relative files without
56
+ a per-agent permission contract.
57
+ - LLMs do not receive direct filesystem access. Agent implementation code
58
+ builds prompts from files and performs writes on behalf of the LLM.
59
+ - Next-agent selection is currently distributed across deterministic code,
60
+ LLM routing output, prompt instructions, and cycle guards.
61
+ - The session folder already acts as the persistent context space for raw data,
62
+ analyses, proposals, traces, RAG material, and final output.
63
+
64
+ V8.0 formalizes these existing mechanisms. It does not create a second product
65
+ pipeline beside them.
66
+
67
+ ---
68
+
69
+ ## Confirmed V8.0 Decisions
70
+
71
+ | Area | Confirmed decision |
72
+ |---|---|
73
+ | Product scope | Polyhedra V8.0 is quant-only. Academic and research agents are removed from the V8.0 product runtime and workflow. |
74
+ | Collaboration model | Quant agents collaborate through artifacts in the session folder instead of relying on one implicit linear mention chain. |
75
+ | Workflow authority | A structured Routing Table controls activation. LLM routing output no longer selects the next workflow agent. |
76
+ | Existing behavior | The Routing Table adopts the current quant logic unless a dependency is explicitly reviewed and changed in this PRD. |
77
+ | Table contents | Agent entries use only exact registered agent names. Inputs, services, helpers, versions, markets, symbols, and humans are not agent entries. |
78
+ | Parallel execution | Agents whose Routing Table dependencies are satisfied may be activated in parallel. |
79
+ | File access | Each agent receives a structured session-artifact ACL defining what it may read, create, overwrite/edit, and list. |
80
+ | Enforcement | Runtime code controls artifact access through the injected file interface. An agent or LLM is not trusted to enforce ACL rules from prompt text. |
81
+ | Contract violations | Unauthorized file access is prevented by construction and covered by contract tests; it is not designed as a normal agent decision or product branch. |
82
+ | Agent I/O | Every quant agent is migrated to typed input and output artifact schemas in V8.0. |
83
+ | Migration | All quant workflow agents migrate to the V8.0 contracts together; V8.0 does not leave a permanent mixed governed/ungoverned workflow. |
84
+ | Artifact storage | Final storage layout follows from the approved dependency, ACL, and typed-schema contracts. It is not designed independently first. |
85
+ | Activation | Each agent declares a supported scope. At the beginning of a run, the runtime calculates every agent's effective scope and freezes the resulting active routing plan. Required dependency outputs then determine when each active agent can run. |
86
+ | RAG | RAG remains part of the quant system and may expose only artifacts permitted by the requesting agent's ACL. |
87
+ | Human role | No human is an agent entry or participant inside the V8.0 Routing Table. Finley remains the product-facing output layer, and the system remains paper-trading only. |
88
+ | UI | The existing UI remains and is extended to show current agent progress, the Routing Table, and ACL information. |
89
+ | Design process | The Routing Table, ACL, and schemas are reviewed one agent group at a time before implementation. |
90
+
91
+ ---
92
+
93
+ ## Structural Requirements
94
+
95
+ ### Routing Table
96
+
97
+ - The Routing Table contains agent entries only.
98
+ - Every agent entry uses its exact registered name.
99
+ - Dependency columns represent required agent outputs, not version labels,
100
+ ticker branches, helper services, session inputs, or LLM-selected routing.
101
+ - Symbol and market applicability are declared as agent supported scope, not
102
+ workflow branches.
103
+ - Independent agents may run in parallel when their required dependencies are
104
+ satisfied.
105
+ - The Routing Table will be defined and approved one agent group at a time.
106
+ - At the beginning of each YOLO run, the runtime calculates each agent's
107
+ effective scope as the intersection of requested tickers and that agent's
108
+ supported scope.
109
+ - An agent is active when its effective scope is not empty.
110
+ - A dependency applies only to the overlapping effective scope of its upstream
111
+ and downstream agents.
112
+ - The resulting active routing plan is fixed for that run. Agent or LLM output cannot
113
+ add, remove, or reroute workflow nodes while the run is in progress.
114
+ - A later YOLO run initializes a new active routing plan. Changes to ticker
115
+ scope take effect in that later run rather than mutating a plan already in
116
+ progress.
117
+ - Agent prompts may request more evidence or report missing input, but they do
118
+ not activate another workflow agent directly.
119
+ - The runtime evaluates dependency completion and activation conditions.
120
+ - Existing LLM routing JSON may remain during migration only as non-authoritative
121
+ diagnostic output; it must not control V8.0 workflow execution.
122
+ - The Routing Table is the runtime workflow definition. It is distinct from the
123
+ `EventRouter` agent, which assigns detected event evidence to in-scope
124
+ tickers but does not activate or skip workflow agents.
125
+
126
+ ### Session-Artifact ACL
127
+
128
+ - Each agent receives explicit `read`, `create`, `edit`, and `list` permissions.
129
+ - Permissions are defined in a structured runtime contract rather than being
130
+ scattered across prompts and agent implementation code.
131
+ - The runtime gives an agent only the artifact operations allowed by its ACL.
132
+ - LLMs do not receive direct filesystem access.
133
+ - Prompt construction and RAG retrieval use the same ACL-filtered artifact view.
134
+ - Agent implementations must not receive an unrestricted session-folder file
135
+ interface after migration.
136
+ - Per-agent artifact permissions will be approved one agent at a time; they are not
137
+ inferred from current unrestricted access.
138
+
139
+ #### ACL Fields
140
+
141
+ The Routing Table determines when an agent runs. The ACL determines which
142
+ artifacts it can read and change, including context retrieved through RAG.
143
+
144
+ | Field | Meaning |
145
+ |---|---|
146
+ | `read` | Artifacts allowed as input. |
147
+ | `create` | Artifacts the agent may create. |
148
+ | `edit` | Existing artifacts the agent may update. |
149
+ | `list` | Session-relative filenames the agent may discover through enumeration. |
150
+
151
+ Every permission field is a list. `[]` grants no permission for that operation.
152
+ Permissions apply within the active session and the agent's effective ticker
153
+ scope. Unlisted artifacts are inaccessible through the runtime file interface.
154
+ All entries are filenames or filename templates relative to the session folder,
155
+ including subdirectories. They are not logical artifact identifiers.
156
+ `{ticker}` resolves only to tickers in the agent's effective scope; `{date}`
157
+ identifies the artifact date within the session, including prior dates needed
158
+ for delta comparisons. Listing returns only filenames allowed by `list`;
159
+ reading their contents separately requires `read` permission.
160
+
161
+ #### ACL Table
162
+
163
+ These permissions are the V8.0 draft based on existing artifact usage. The
164
+ table covers all 19 registered quant agents; it does not claim that runtime ACL
165
+ enforcement is already implemented.
166
+
167
+ | Agent | `read` | `create` | `edit` | `list` |
168
+ |---|---|---|---|---|
169
+ | `DataFetcher` | `[quant/raw/{ticker}_{date}.json, quant/raw/{ticker}_{date}_summary.md]` | `[quant/raw/{ticker}_{date}.json, quant/raw/{ticker}_{date}_summary.md]` | `[quant/raw/{ticker}_{date}.json, quant/raw/{ticker}_{date}_summary.md]` | `[quant/raw/{ticker}_{date}.json, quant/raw/{ticker}_{date}_summary.md]` |
170
+ | `OptionsFlowWatcher` | `[]` | `[quant/options_flow_{date}.md]` | `[quant/options_flow_{date}.md]` | `[]` |
171
+ | `TrendAnalyst` | `[quant/raw/{ticker}_{date}_summary.md]` | `[quant/trend_analysis_{date}.md]` | `[quant/trend_analysis_{date}.md]` | `[quant/raw/{ticker}_{date}_summary.md]` |
172
+ | `SentimentAnalyst` | `[quant/raw/{ticker}_{date}_summary.md, quant/trend_analysis_{date}.md]` | `[quant/sentiment_analysis_{date}.md]` | `[quant/sentiment_analysis_{date}.md]` | `[quant/raw/{ticker}_{date}_summary.md]` |
173
+ | `MarketEventWatcher` | `[quant/raw/{ticker}_{date}_summary.md, quant/trend_analysis_{date}.md]` | `[quant/market_events_{date}.md]` | `[quant/market_events_{date}.md]` | `[quant/raw/{ticker}_{date}_summary.md]` |
174
+ | `MacroContextWatcher` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md]` | `[quant/macro_context_{date}.md]` | `[quant/macro_context_{date}.md]` | `[]` |
175
+ | `UnusualEventDetector` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md, quant/macro_context_{date}.md]` | `[quant/unusual_events_{date}.md]` | `[quant/unusual_events_{date}.md]` | `[]` |
176
+ | `EventRouter` | `[quant/unusual_events_{date}.md, quant/market_events_{date}.md, quant/options_flow_{date}.md]` | `[quant/event_route_{date}.md]` | `[quant/event_route_{date}.md]` | `[]` |
177
+ | `BTCAnalyst` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md, quant/macro_context_{date}.md, quant/unusual_events_{date}.md, quant/event_route_{date}.md, quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md]` | `[quant/btc_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[quant/btc_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[]` |
178
+ | `SPYAnalyst` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md, quant/macro_context_{date}.md, quant/unusual_events_{date}.md, quant/event_route_{date}.md, quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md]` | `[quant/spy_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[quant/spy_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[]` |
179
+ | `QQQAnalyst` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md, quant/macro_context_{date}.md, quant/unusual_events_{date}.md, quant/event_route_{date}.md, quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md]` | `[quant/qqq_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[quant/qqq_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[]` |
180
+ | `GLDAnalyst` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md, quant/macro_context_{date}.md, quant/unusual_events_{date}.md, quant/event_route_{date}.md, quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md]` | `[quant/gld_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[quant/gld_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[]` |
181
+ | `QuantResearcher` | `[quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md, quant/asset_analysis_{date}.md, quant/macro_context_{date}.md, quant/unusual_events_{date}.md]` | `[quant/signals_{date}.md]` | `[quant/signals_{date}.md]` | `[]` |
182
+ | `Backtester` | `[quant/signals_{date}.md, quant/raw/{ticker}_{date}_summary.md]` | `[quant/backtest_results_{date}.md]` | `[quant/backtest_results_{date}.md]` | `[quant/raw/{ticker}_{date}_summary.md]` |
183
+ | `RiskAnalyst` | `[quant/backtest_results_{date}.md, quant/trend_analysis_{date}.md, quant/asset_analysis_{date}.md, quant/macro_context_{date}.md]` | `[quant/risk_assessment_{date}.md]` | `[quant/risk_assessment_{date}.md]` | `[]` |
184
+ | `QuantStrategist` | `[quant/risk_assessment_{date}.md, quant/backtest_results_{date}.md, quant/sentiment_analysis_{date}.md, quant/signals_{date}.md, quant/asset_analysis_{date}.md, quant/macro_context_{date}.md, quant/strategist_performance.json]` | `[quant/trade_proposals_{date}.md, quant/strategist_performance.json]` | `[quant/trade_proposals_{date}.md, quant/strategist_performance.json]` | `[]` |
185
+ | `Publisher` | `[quant/trade_proposals_{date}.md, quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md, quant/risk_assessment_{date}.md, quant/asset_analysis_{date}.md, quant/macro_context_{date}.md]` | `[quant/post_{date}.md]` | `[quant/post_{date}.md]` | `[]` |
186
+ | `VizAgent` | `[quant/raw/{ticker}_{date}.json, quant/backtest_results_{date}.md, quant/risk_assessment_{date}.md]` | `[quant/viz/candlestick_{ticker}_{date}.png, quant/viz/rsi_macd_{ticker}_{date}.png, quant/viz/backtest_{date}.png, quant/viz/risk_heatmap_{date}.png, quant/viz/portfolio_pnl_{date}.png]` | `[quant/viz/candlestick_{ticker}_{date}.png, quant/viz/rsi_macd_{ticker}_{date}.png, quant/viz/backtest_{date}.png, quant/viz/risk_heatmap_{date}.png, quant/viz/portfolio_pnl_{date}.png]` | `[quant/raw/{ticker}_{date}.json]` |
187
+ | `PortfolioMonitor` | `[]` | `[quant/portfolio_log_{date}.md]` | `[quant/portfolio_log_{date}.md]` | `[]` |
188
+
189
+ #### Baseline File Permissions
190
+
191
+ These lists extend the corresponding agent's `read` and `list` permissions
192
+ above for session-delta runs. `{baseline}` is the runtime-selected existing
193
+ baseline directory inside this session. `{date}` is the saved artifact date.
194
+ No agent receives `create` or `edit` permission for baseline files. The
195
+ runtime preserves those snapshots. Trade-state context uses the selected
196
+ proposal or no-trade/watch file when available.
197
+
198
+ | Agent | Additional `read` | Additional `list` |
199
+ |---|---|---|
200
+ | `DataFetcher` | `[quant/yolo_baselines/{baseline}/quant/raw/{ticker}_{date}_summary.md]` | `[quant/yolo_baselines/{baseline}/quant/raw/{ticker}_{date}_summary.md]` |
201
+ | `OptionsFlowWatcher` | `[quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
202
+ | `TrendAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
203
+ | `SentimentAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
204
+ | `MarketEventWatcher` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
205
+ | `MacroContextWatcher` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
206
+ | `UnusualEventDetector` | `[quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
207
+ | `EventRouter` | `[quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
208
+ | `BTCAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
209
+ | `SPYAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
210
+ | `QQQAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
211
+ | `GLDAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
212
+ | `QuantResearcher` | `[quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/backtest_results_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
213
+ | `Backtester` | `[quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/backtest_results_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md]` | `[]` |
214
+ | `RiskAnalyst` | `[quant/yolo_baselines/{baseline}/quant/backtest_results_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
215
+ | `QuantStrategist` | `[quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/backtest_results_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
216
+ | `Publisher` | `[quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md]` | `[]` |
217
+ | `VizAgent` | `[]` | `[]` |
218
+ | `PortfolioMonitor` | `[]` | `[]` |
219
+
220
+ #### Permission Boundaries
221
+
222
+ - For dated files, `create` and `edit` refer to working outputs for the current run's date.
223
+ Historical working files and baseline snapshots are read-only context.
224
+ - Read permission does not add a Routing Table dependency or imply that an
225
+ optional file is available. For example, current trend context is an optional
226
+ input to `SentimentAnalyst` and `MarketEventWatcher` under the agreed routing.
227
+ - `DataFetcher` no longer needs to read trend output solely to choose the next
228
+ agent; that decision belongs to the Routing Table.
229
+ - Helpers acting for an agent, including provider writers and committee
230
+ tracking, use that agent's runtime-controlled permissions.
231
+ - Writes to `quant/strategist_performance.json` are performed by the trusted
232
+ performance tracker for `QuantStrategist`. LLM-emitted weights do not replace
233
+ runtime-owned weights.
234
+ - The shared `quant/asset_analysis_{date}.md` entries record the existing
235
+ append behavior of all four asset analysts. Filename ACL alone cannot limit
236
+ an edit to one analyst's section. Shared-file ownership and parallel writes
237
+ must be settled with typed schemas and artifact storage before this ACL is
238
+ implemented.
239
+ - Shared reports may contain multiple tickers. Their filename permission alone
240
+ does not enforce the effective ticker scope; the typed input contract must
241
+ define the scope-filtered content exposed to each agent.
242
+ - Session metadata, selected portfolio state, prior backtest state, and recent
243
+ conversation context currently arrive through runtime inputs. These tables
244
+ do not grant agents unrestricted access to `research_state.json` or
245
+ `thread.jsonl`. Their allowed input fields remain part of the typed-schema
246
+ discussion. Runtime state patches, traces, snapshots, and evidence-ledger
247
+ writes remain runtime-owned.
248
+ - Listing and RAG retrieval must observe the same session and filename
249
+ permissions. Final storage changes must update these tables accordingly.
250
+
251
+
252
+ #### File Content Reference
253
+
254
+ This table explains the files referenced by the ACL above using their current
255
+ contents and explicitly identified V8 changes. Exact typed schemas remain a
256
+ separate design step. A listed filename describes an artifact contract, not a
257
+ guarantee that a provider or agent successfully produced it in every run.
258
+
259
+ | Filename relative to session folder | Format | Content | Purpose |
260
+ |---|---|---|---|
261
+ | `quant/raw/{ticker}_{date}.json` | JSON | Ticker and fetch timestamp; available daily OHLCV history; computed SMA-20, EMA-20, RSI-14, and MACD series; news records; earnings records where applicable; provider errors, partial-fetch indicators, and OHLCV quality metadata when present. | Structured fetched market dataset used to generate summaries and support downstream analysis. Despite the `raw` directory name, this file contains normalized data and computed indicators rather than an untouched API response. |
262
+ | `quant/raw/{ticker}_{date}_summary.md` | Markdown | Ticker and fetch timestamp; data-quality notes and excluded rows when present; latest 10 available OHLCV rows; latest technical-indicator values; up to 15 news headlines with available sentiment fields; up to four quarterly earnings records where applicable; a prior-baseline summary excerpt during session-delta runs when available. | Readable market-data context for downstream agents, including context for comparing the current run with the previous baseline. |
263
+ | `quant/trend_analysis_{date}.md` | Markdown | Technical interpretation of price structure, indicators, trend direction, and uncertainty; delta observations where available. | Technical context produced by TrendAnalyst. |
264
+ | `quant/sentiment_analysis_{date}.md` | Markdown | News and earnings sentiment assessment, cited themes, sentiment/technical alignment, and insufficient-data notes. | Sentiment context produced by SentimentAnalyst. |
265
+ | `quant/market_events_{date}.md` | Markdown | In-scope raw summary excerpts, optional existing trend context, check timestamp, and prior-session context. | Market context assembled by MarketEventWatcher; the current implementation does not fetch a separate event feed. |
266
+ | `quant/options_flow_{date}.md` | Markdown | Options provider status and timestamp, sampled contracts and expirations, call/put volume, open interest, IV summaries, preliminary FLOW_CANDIDATE observations, and explicit data gaps. | Options evidence from OptionsFlowWatcher, distinguishing options-chain context from unsupported unusual-flow claims. |
267
+ | `quant/macro_context_{date}.md` | Markdown | LLM macro main-line assessment, candidate drivers, relevance weights, confidence, uncertainty, and affected markets, or an explicit analysis-unavailable result. | Macro interpretation produced by MacroContextWatcher. |
268
+ | `quant/unusual_events_{date}.md` | Markdown | LLM event candidates with event type, affected markets, significance, rationale, and missing evidence; a no-meaningful-event assessment where appropriate. | Event detection output from UnusualEventDetector. |
269
+ | `quant/event_route_{date}.md` | Markdown | Currently selected symbols, selected analyst names, rationale, and delta context. V8 uses this output for event-to-ticker evidence assignments under the fixed Routing Table. | Evidence assignment output from EventRouter; it cannot activate agents in V8. |
270
+ | `quant/btc_analysis_{date}.md` | Markdown | BTC market interpretation, weighted signals, confidence, setup hypothesis, confirmation/invalidation conditions, and recommended outcome or explicit analysis failure. | Individual output of BTCAnalyst. |
271
+ | `quant/spy_analysis_{date}.md` | Markdown | SPY market interpretation, weighted signals, confidence, setup hypothesis, confirmation/invalidation conditions, and recommended outcome or explicit analysis failure. | Individual output of SPYAnalyst. |
272
+ | `quant/qqq_analysis_{date}.md` | Markdown | QQQ market interpretation, weighted signals, confidence, setup hypothesis, confirmation/invalidation conditions, and recommended outcome or explicit analysis failure. | Individual output of QQQAnalyst. |
273
+ | `quant/gld_analysis_{date}.md` | Markdown | GLD market interpretation, weighted signals, confidence, setup hypothesis, confirmation/invalidation conditions, and recommended outcome or explicit analysis failure. | Individual output of GLDAnalyst. |
274
+ | `quant/asset_analysis_{date}.md` | Markdown | Combined ticker-labelled sections appended by the specialized analysts. | Shared specialized-analysis input for QuantResearcher, RiskAnalyst, QuantStrategist, and Publisher; write ownership remains a storage decision. |
275
+ | `quant/signals_{date}.md` | Markdown | Named signal hypotheses, entry/exit conditions, confidence, falsification criteria, and run/delta updates. | QuantResearcher output for Backtester and strategy review. |
276
+ | `quant/backtest_results_{date}.md` | Markdown | LLM-produced backtest assessment from supplied signals and market summaries, approximate metrics, assumptions, and limitations. | Backtester output for risk and strategy review; its presence alone does not establish an executed historical experiment. |
277
+ | `quant/risk_assessment_{date}.md` | Markdown | Risk ratings, concentration/correlation and drawdown assessment, scenarios, and risk verdicts using available analysis and portfolio context. | RiskAnalyst output consumed before strategy decisions. |
278
+ | `quant/trade_proposals_{date}.md` | Markdown | Strategy-review narrative, committee summary, prior proposal lifecycle updates, and paper-trading conclusions. Structured proposals also travel in the runtime agent output/state patch. | QuantStrategist's readable strategy result and prior trade-state context. |
279
+ | `quant/no_trade_watch_{date}.md` | Markdown | Explicit no-trade or watch state when such a prior artifact exists. | Supported alternative baseline trade-state input; the ACL does not introduce a new writer for this file. |
280
+ | `quant/strategist_performance.json` | JSON | Trusted member weights, vote history, weight-change history, and latest weighted aggregation. | Session-owned committee record maintained through the existing performance tracker. |
281
+ | `quant/post_{date}.md` | Markdown | Finley's readable final market output, baseline/delta interpretation, and paper-trading disclaimer. | Publisher's user-facing result. |
282
+ | `quant/portfolio_log_{date}.md` | Markdown | Timestamped open-position checks, available current prices, threshold breaches, missing-price notes, and alerts. | PortfolioMonitor's daily monitoring record. |
283
+ | `quant/viz/candlestick_{ticker}_{date}.png` | PNG chart | Price candles, volume, and a moving-average overlay when usable source data exists. | Market-price visualization produced by VizAgent. |
284
+ | `quant/viz/rsi_macd_{ticker}_{date}.png` | PNG chart | RSI and MACD panels based on available indicator data. | Technical-indicator visualization produced by VizAgent. |
285
+ | `quant/viz/backtest_{date}.png` | PNG chart | Signal win-rate chart from parseable backtest metrics. | Backtest visualization produced by VizAgent. |
286
+ | `quant/viz/risk_heatmap_{date}.png` | PNG chart | Risk verdicts rendered as a labelled risk-rating chart. | Risk visualization produced by VizAgent. |
287
+ | `quant/viz/portfolio_pnl_{date}.png` | PNG chart | Currently position-size bars and entry-price markers from portfolio state. | Portfolio visualization produced by VizAgent; despite its filename, the current code does not calculate realized/unrealized P&L here. |
288
+ | `quant/yolo_baselines/{baseline}/quant/...` | Same as saved file | Saved copies of the exact quant filenames enumerated in the Baseline File Permissions table, retaining each original file's content and relative path. | Read-only prior-run context. The ellipsis here describes that directory layout and is not an ACL wildcard. |
289
+ | `research_state.json` | JSON | Runtime session state, including quant watchlist, portfolio, proposals, prior backtest state, and YOLO metadata. | Runtime-owned state source for selected typed agent inputs; not a blanket file permission. |
290
+ | `thread.jsonl` | JSON Lines | Recorded conversation and agent messages for the session. | Runtime-owned conversation history; agent context must be filtered according to its allowed inputs. |
291
+
292
+ Missing sections do not imply zero values or neutral evidence. Availability and
293
+ data-quality metadata must be respected when consuming these files.
294
+
295
+ ### Typed Artifact Schemas
296
+
297
+ - Every migrated quant agent has typed input and output artifact contracts.
298
+ - Agent activation is based on declared dependencies and valid required input
299
+ artifacts.
300
+ - Required inputs, optional inputs, produced outputs, provenance, freshness,
301
+ and explicit data-gap states are represented structurally where applicable.
302
+ - A downstream agent receives only schema-valid dependency outputs exposed by
303
+ its ACL.
304
+ - Human-readable markdown may remain as a rendered artifact, but markdown
305
+ conventions alone are not the V8.0 machine contract.
306
+ - Artifact storage details will be finalized after the dependency, ACL, and
307
+ schema contracts are agreed.
308
+
309
+ ### Runtime And Product Boundaries
310
+
311
+ - All quant agents migrate to the V8.0 contract together.
312
+ - No human is an agent entry inside the V8.0 Routing Table.
313
+ - Current UI behavior is retained and extended to show agent progress, the
314
+ Routing Table, and ACL information.
315
+ - Existing strategy logic is preserved unless this PRD explicitly changes it.
316
+
317
+ ### Session Collaboration
318
+
319
+ - The session folder is the shared persistent context space for one analysis
320
+ session.
321
+ - Agents collaborate by producing and consuming governed session artifacts.
322
+ - Baseline and session-delta YOLO behavior continue to use the same agents and
323
+ the same Routing Table.
324
+ - A later run may reuse prior session artifacts only when its dependency
325
+ contract, ACL, and freshness requirements allow it.
326
+ - The Routing Table controls readiness; the ACL controls visibility and
327
+ mutation; typed schemas control the meaning of exchanged artifacts.
328
+
329
+ ### UI Visibility
330
+
331
+ The V8.0 UI retains the current YOLO run experience and adds:
332
+
333
+ 1. Current agent activation and completion state from the Routing Table.
334
+ 2. The Routing Table using exact registered agent names.
335
+ 3. ACL information showing which session artifacts each agent may read and
336
+ produce.
337
+
338
+ The UI must not present services, schemas, ACL entries, or dependency-engine
339
+ internals as additional agents.
340
+
341
+ ---
342
+
343
+ ## Agreed Routing Table
344
+
345
+ This table contains every registered quant agent. Scope is one of four enum
346
+ values. A dependency applies only where the two agents' effective scopes
347
+ overlap. `Required agent dependencies` is always a list; `[]` means the agent
348
+ has no required upstream agent.
349
+
350
+ ```text
351
+ QUANT = any valid quant ticker
352
+ GENERAL = any valid quant ticker except BTC, SPY, QQQ, GLD
353
+ SPECIALIZED = BTC, SPY, QQQ, GLD
354
+ OPTIONS = SPY, QQQ, GLD
355
+ ```
356
+
357
+ | Agent | Required agent dependencies | Scope |
358
+ |---|---|---|
359
+ | `DataFetcher` | `[]` | `QUANT` |
360
+ | `OptionsFlowWatcher` | `[]` | `OPTIONS` |
361
+ | `TrendAnalyst` | `[DataFetcher]` | `QUANT` |
362
+ | `SentimentAnalyst` | `[DataFetcher]` | `GENERAL` |
363
+ | `MarketEventWatcher` | `[DataFetcher]` | `SPECIALIZED` |
364
+ | `MacroContextWatcher` | `[MarketEventWatcher, OptionsFlowWatcher]` | `SPECIALIZED` |
365
+ | `UnusualEventDetector` | `[MarketEventWatcher, MacroContextWatcher, OptionsFlowWatcher]` | `SPECIALIZED` |
366
+ | `EventRouter` | `[UnusualEventDetector]` | `SPECIALIZED` |
367
+ | `BTCAnalyst` | `[TrendAnalyst, EventRouter]` | `SPECIALIZED` |
368
+ | `SPYAnalyst` | `[TrendAnalyst, EventRouter]` | `SPECIALIZED` |
369
+ | `QQQAnalyst` | `[TrendAnalyst, EventRouter]` | `SPECIALIZED` |
370
+ | `GLDAnalyst` | `[TrendAnalyst, EventRouter]` | `SPECIALIZED` |
371
+ | `QuantResearcher` | `[TrendAnalyst, SentimentAnalyst, BTCAnalyst, SPYAnalyst, QQQAnalyst, GLDAnalyst]` | `QUANT` |
372
+ | `Backtester` | `[QuantResearcher]` | `QUANT` |
373
+ | `RiskAnalyst` | `[Backtester]` | `QUANT` |
374
+ | `QuantStrategist` | `[RiskAnalyst]` | `QUANT` |
375
+ | `Publisher` | `[QuantStrategist]` | `QUANT` |
376
+ | `VizAgent` | `[]` | `QUANT` |
377
+ | `PortfolioMonitor` | `[]` | `QUANT` |
378
+
379
+ `BTCAnalyst`, `SPYAnalyst`, `QQQAnalyst`, and `GLDAnalyst` use the
380
+ `SPECIALIZED` scope enum. Their existing fixed `symbol` property further
381
+ restricts each effective scope to its own ticker; the ticker does not create a
382
+ new scope enum.
383
+
384
+ When their effective scopes are not empty, `TrendAnalyst`, `SentimentAnalyst`,
385
+ and `MarketEventWatcher` become eligible in parallel after `DataFetcher`
386
+ completes successfully for the corresponding ticker scope.
387
+
388
+ ### Root Agents
389
+
390
+ `DataFetcher`, `OptionsFlowWatcher`, and `VizAgent` have no required upstream
391
+ agents. Their ticker, date, session, provider, run-mode, or visualization inputs
392
+ are input-contract fields and must not be represented as agent entries.
393
+
394
+ `PortfolioMonitor` is also a root agent, but only in a separately initialized
395
+ portfolio-monitor run. It is not added to the active YOLO routing plan.
396
+
397
+ ### Conditional Joins
398
+
399
+ The Routing Table uses effective-scope overlap to resolve joins:
400
+
401
+ - `MacroContextWatcher` waits for `OptionsFlowWatcher` only for `SPY`, `QQQ`,
402
+ and `GLD`; BTC has no options dependency.
403
+ - `QuantResearcher` waits for `SentimentAnalyst` only for general-market scope.
404
+ - `QuantResearcher` waits for each specialized analyst whose single-symbol
405
+ effective scope is active.
406
+ - Mixed-ticker runs may therefore activate both the general analysis branch and
407
+ one or more specialized analysis branches before joining at
408
+ `QuantResearcher`.
409
+
410
+ ### Run Routing Initialization
411
+
412
+ At the beginning of each YOLO run, the runtime:
413
+
414
+ 1. Normalizes the complete ticker scope.
415
+ 2. Selects the execution context: YOLO, visualization request, or
416
+ portfolio-monitor run.
417
+ 3. Intersects the requested tickers with each applicable agent's supported
418
+ scope.
419
+ 4. Stores the resulting effective scope for each agent.
420
+ 5. Removes agents with an empty effective scope, agents outside the selected
421
+ execution context, and dependencies with no
422
+ overlapping effective scope.
423
+ 6. Creates the fixed active routing plan for that run.
424
+ 7. Activates each included agent when its applicable required dependencies have
425
+ produced valid typed outputs.
426
+
427
+ Inactive agents are absent from that run's active routing plan. A data-gap
428
+ output does not change the plan; it is a typed result consumed by already
429
+ activated downstream agents. Mixed ticker scopes may activate both general and
430
+ specialized agents in the same run, with each agent receiving only its
431
+ applicable ticker scope.
432
+
433
+ ---
434
+
435
+ ## Remaining Contract Decisions
436
+
437
+ The Routing Table and draft ACL rows now cover all registered quant agents.
438
+ The remaining decisions are typed input/output schemas, shared-file ownership
439
+ and ticker filtering, final artifact storage, and UI presentation. The tables
440
+ are design specifications; runtime migration and enforcement are not yet
441
+ implemented.
442
+
443
+ ---
444
+
445
+ ## V8.0 Definition Checklist
446
+
447
+ - [x] Limit V8.0 product scope to quant agents.
448
+ - [x] Define the Routing Table as the workflow authority.
449
+ - [x] Require agent-only Routing Table entries with exact registered names.
450
+ - [x] Define the first data-and-context dependency slice.
451
+ - [x] Define the `UnusualEventDetector` dependency slice.
452
+ - [x] Add all registered quant agents to the Routing Table.
453
+ - [x] Define the complete Routing Table at the agent-dependency and scope level.
454
+ - [x] Draft filename-based ACL rows and file-content references for all quant agents.
455
+ - [x] Record baseline snapshot read permissions for session-delta context.
456
+ - [ ] Finalize shared-file ownership and scope-filtered access with typed schemas.
457
+ - [ ] Finalize the ACL contract for each quant agent after those decisions.
458
+ - [ ] Define typed input and output artifact schemas for each quant agent.
459
+ - [ ] Finalize artifact storage from the approved contracts.
460
+ - [ ] Define UI presentation for dependency and ACL state.
461
+ - [ ] Write the V8.0 implementation and verification plan.