yf176 commited on
Commit
1da4dfb
·
1 Parent(s): 038d10f

docs: add phased V8 implementation and verification plan

Browse files
Files changed (1) hide show
  1. docs/V8.0_IMPLEMENTATION_PLAN.md +270 -0
docs/V8.0_IMPLEMENTATION_PLAN.md ADDED
@@ -0,0 +1,270 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Polyhedra V8.0 Implementation Plan
2
+
3
+ Status: planned; no V8.0 runtime implementation or deployment is asserted.
4
+ Source of truth: [polyhedraV8.0.md](polyhedraV8.0.md).
5
+ Inherited behavior: V7.1 replay and evidence ledger, V7.0 session-delta YOLO,
6
+ and the existing quant agents and Finley output.
7
+
8
+ ## Working Rules
9
+
10
+ - Keep the existing quant agent names and service boundaries. Implement inside
11
+ the existing agents, core, services, messaging, and web modules; do not add
12
+ version-named agent directories or a second product pipeline.
13
+ - Complete phases in order. Agent migrations may be developed incrementally,
14
+ but release the governed quant runtime only after all registered quant agents
15
+ pass the migration gate. Do not deploy an intermediate mixed workflow.
16
+ - Every function point below starts unchecked. Check it only after its code,
17
+ relevant tests, and PRD acceptance criteria are verified. Record the evidence
18
+ with the function-point ID in the Verification Record.
19
+ - Use existing provider configuration and dependencies. No new API keys,
20
+ integrations, services, authentication tokens, or schedulers are authorized
21
+ by this plan. Report a demonstrated provider entitlement gap before adding
22
+ a replacement provider.
23
+ - Keep commits separated by function point or coherent module boundary.
24
+ Commit and push when requested; deployment and live tests are separate from
25
+ writing this plan.
26
+ - Preserve the halted distilled committee expansion and current trusted
27
+ performance-weight behavior. This migration changes artifact contracts and
28
+ execution control, not the experiment's analyst membership.
29
+
30
+ ## Phase 1: Contracts
31
+
32
+ Primary modules: `agents/quant/outputs.py`, `agents/base.py`, `core/role_registry.py`,
33
+ and a repo-packaged routing/ACL definition loaded by the existing runtime.
34
+
35
+ - [ ] C01 Encode all 19 routing entries, exact registered names, four scope
36
+ enums, fixed asset symbols, execution contexts, and required dependency lists
37
+ in one structured definition. Reject unknown agents and dependency cycles.
38
+ - [ ] C02 Encode the PRD filename ACL and baseline ACL in the same contract
39
+ source. Ensure runtime loading works in the built package and deployment,
40
+ without a dependency on desktop skills or developer machine paths.
41
+ - [ ] C03 Define common typed input, artifact, reference, evidence, data-issue,
42
+ and delta models. Resolve every nested type named in the PRD to explicit
43
+ fields, units, nullability, requiredness, and validation constraints.
44
+ - [ ] C04 Implement the DataFetcher manifest and per-ticker MarketDataArtifact
45
+ models, including component applicability, empty successful feeds, partial
46
+ coverage, freshness, and provider errors without ticker status suffixes.
47
+ - [ ] C05 Implement typed input/output models for each remaining agent,
48
+ preserving distinct concrete producer literals for the four asset analysts.
49
+ - [ ] C06 Define reference identity and schema-version validation for JSON and
50
+ rendering references. Distinguish LONG/SHORT trade direction from analytical
51
+ market direction. Keep unknown values null rather than zero or fake metrics.
52
+ - [ ] C07 Validate conditional decisions: trade levels only for actual paper
53
+ suggestions, no conflicting symbols, at most three final proposals, rejected
54
+ signals excluded, and elevated risk accompanied by mitigation.
55
+ - [ ] C08 Keep data availability separate from execution state. A recorded
56
+ failure must not validate as a successful market NO_TRADE conclusion.
57
+
58
+ Gate: positive and negative schema cases, registry coverage, filename ownership,
59
+ scope enums, and cycle validation pass. Verify serialized round trips and
60
+ malformed LLM/provider payloads, not just class construction.
61
+
62
+ ## Phase 2: Session Artifacts And ACL
63
+
64
+ Primary modules: `services/file_writer.py`, `core/session.py`,
65
+ `core/yolo_context.py`, existing RAG/context services, and run persistence in `app.py`.
66
+
67
+ - [ ] A01 Allocate unique run IDs for every execution, including same-day
68
+ runs; create the PRD run directory and retain the existing session identity.
69
+ - [ ] A02 Inject a scoped file interface enforcing read/create/edit/list,
70
+ path resolution, ticker scope, current/source/baseline run bindings, and
71
+ read-only published outputs. Block traversal, cross-session paths, and
72
+ symlink escapes through the same interface.
73
+ - [ ] A03 Apply permissions to provider writes, renderers, prompt construction,
74
+ and RAG retrieval. Ensure no helper bypasses the injected file boundary.
75
+ - [ ] A04 Validate and publish JSON atomically; record actual typed input
76
+ snapshots and artifact references. Preserve valid analysis when rendering
77
+ fails, with the rendering error recorded separately.
78
+ - [ ] A05 Enforce one owner per agent output. Build the runtime-owned
79
+ AssetAnalysisCollection from the selected run's analyst outputs, with explicit
80
+ missing/unavailable contributions and scope filtering for each consumer.
81
+ - [ ] A06 Select and freeze an eligible prior completed YOLO run for delta
82
+ context. Handle new tickers, unavailable baseline fields, and unsupported
83
+ schema versions explicitly. Failed runs do not replace the eligible baseline.
84
+ - [ ] A07 Preserve legacy replay/files and session paper positions. Establish
85
+ a typed baseline when only legacy artifacts exist; do not parse old Markdown
86
+ into invented typed evidence or overwrite historical snapshots.
87
+ - [ ] A08 Extend the existing export to include all run artifacts, inputs,
88
+ renderings, charts, references, replay records, and available evidence ledger.
89
+ Verify all references inside a downloaded multi-run session resolve correctly.
90
+
91
+ Gate: isolated session tests demonstrate ownership, immutable publication,
92
+ baseline selection, RAG filtering, same-day run isolation, export completeness,
93
+ and preservation of existing files. No runtime producer has blanket file access.
94
+
95
+ ## Phase 3: Dependency Execution
96
+
97
+ Primary modules: `agents/coordinator.py`, `core/agent_router.py`,
98
+ `core/eventbus.py`, `core/template_builder.py`, `core/cost_gate.py`, and
99
+ `core/state_patcher.py`.
100
+
101
+ - [ ] R01 Build the active routing plan once from execution context and
102
+ normalized tickers; store supported/effective scope and pruned dependency lists.
103
+ - [ ] R02 Activate ready agents in parallel and publish each completion once.
104
+ Evaluate overlapping scope at joins; a BTC run never waits for ETF options.
105
+ - [ ] R03 Resolve inputs from published dependency artifacts and the ACL.
106
+ Capture optional inputs at activation; do not race-read mutable upstream files.
107
+ - [ ] R04 Propagate typed partial/unavailable results without treating missing
108
+ outputs as success. Record failed agents and the blocked dependents by name;
109
+ allow unrelated ready work to finish under the same fixed plan.
110
+ - [ ] R05 Remove next-role authority from agent prompts, response mentions,
111
+ cycle guards, and deterministic branch helpers on governed quant execution.
112
+ EventRouter assigns evidence only and cannot expand scope or activate agents.
113
+ - [ ] R06 Preserve cost/token gates, trace logging, and coordinated state
114
+ patches during parallel work. Prevent duplicate strategy/performance updates.
115
+ - [ ] R07 Keep human outside the V8 activation table and automated run. Legacy
116
+ ROUTE_TO_HUMAN labels or approval metadata must not create a human checkpoint,
117
+ route, or automatic trading action in V8. Preserve the explanation as an
118
+ unavailable/deferred result according to the typed contract.
119
+ - [ ] R08 Derive run and agent statuses from activation/publication/error
120
+ records. A quiet LLM request is not blocked solely because Slack is silent.
121
+
122
+ Gate: controlled async tests prove overlap, join ordering, one activation per
123
+ agent, mixed ticker scopes, failed dependency handling, and deterministic input
124
+ selection. Use controlled producers for scheduler tests; these are not live
125
+ LLM or provider verification.
126
+
127
+ ## Phase 4: Agent Migration
128
+
129
+ For each checkbox, migrate input construction, real agent execution, structured
130
+ parsing, artifact publication, baseline context, and declared output rendering.
131
+ Verify the agent's exact input/output model and ACL using representative data
132
+ and an explicit missing-input case. Keep existing reasoning duties intact.
133
+
134
+ - [ ] M01 DataFetcher: retain fetch/fallback/normalization and computed
135
+ indicators; persist component quality and actual timestamps through its ACL.
136
+ - [ ] M02 OptionsFlowWatcher: preserve normalized contracts and bounded sampling;
137
+ distinguish market context, candidates, and evidenced unusual flow. Retain
138
+ missing versus zero values and record unsupported flow capabilities.
139
+ - [ ] M03 TrendAnalyst: perform LLM technical interpretation from valid typed
140
+ prices/indicators and publish cited trend records with explicit data gaps.
141
+ - [ ] M04 SentimentAnalyst: perform LLM sentiment interpretation for GENERAL
142
+ scope; distinguish unscored or thin news from genuinely neutral evidence.
143
+ - [ ] M05 MarketEventWatcher: organize DataFetcher evidence and compare prior
144
+ context without asserting a nonexistent live event provider.
145
+ - [ ] M06 MacroContextWatcher: preserve LLM main-line interpretation, weighted
146
+ drivers, scope, contradictions, and uncertainty.
147
+ - [ ] M07 UnusualEventDetector: preserve LLM event assessment and record
148
+ meaningful, suppressed, unchanged, and unsupported evidence distinctly.
149
+ - [ ] M08 EventRouter: publish typed event-to-ticker assignments within the
150
+ initialized scope; never bypass the fixed routing plan.
151
+ - [ ] M09 BTCAnalyst: migrate its BTC-specific reasoning and delta contract.
152
+ - [ ] M10 SPYAnalyst: migrate its SPY-specific reasoning and delta contract.
153
+ - [ ] M11 QQQAnalyst: migrate its QQQ-specific reasoning and delta contract.
154
+ - [ ] M12 GLDAnalyst: migrate its GLD-specific reasoning and delta contract.
155
+ - [ ] M13 QuantResearcher: consume the conditional join, retain signal IDs
156
+ across delta updates, and allow an evidence-supported empty signal result.
157
+ - [ ] M14 Backtester: retain validation duties and distinguish LLM assessment
158
+ from executed historical simulation. Unsupported metrics remain null with
159
+ reasons; this phase does not introduce a historical execution engine.
160
+ - [ ] M15 RiskAnalyst: retain signal verdicts and paper-portfolio context;
161
+ forward a completed risk result even when all candidate signals are rejected.
162
+ - [ ] M16 QuantStrategist: retain proposal/no-trade/watch reasoning, lifecycle
163
+ updates, committee votes, and trusted weights. Do not infer a decision from
164
+ fallback error prose or permit the LLM to alter member weights.
165
+ - [ ] M17 Publisher: retain Finley's readable baseline/delta output and exact
166
+ proposal values; distinguish data loss, unavailable analysis, genuine no-trade,
167
+ and watch outcomes without a required human activation.
168
+ - [ ] M18 VizAgent: use typed chart sources, persist real PNG bytes through
169
+ the allowed interface, and record chart sources; remain outside normal YOLO.
170
+ - [ ] M19 PortfolioMonitor: use typed open-position/quote inputs, preserve
171
+ threshold checks and provenance, and publish alerts without closing positions.
172
+
173
+ Gate: all 19 migrations pass agent-focused tests and integrated typed handoff
174
+ tests. A model existing in outputs.py is not sufficient: runtime traces and
175
+ persisted artifacts must demonstrate use on the actual execution path.
176
+
177
+ ## Phase 5: Runtime And Product Integration
178
+
179
+ - [ ] I01 Make UI and Slack invoke the same coordinator, registry, routing
180
+ plan, session state, provider configuration, and typed artifact runtime.
181
+ - [ ] I02 Preserve existing quant entry commands and session behavior.
182
+ Scope determines specialization; avoid a new version-specific product command.
183
+ - [ ] I03 Remove academic-specific agents, registrations, prompts, commands,
184
+ and product descriptions from the quant-only runtime. Trace shared imports
185
+ before removal; preserve quant RAG, LLM, session, and export infrastructure.
186
+ - [ ] I04 Persist run-specific routing and permission snapshots in the existing
187
+ replay record. Keep recorded failures and last available Finley output
188
+ associated with the correct run, without reusing another run's result.
189
+ - [ ] I05 Build evidence ledgers from actual input/output references and
190
+ recorded exclusions. Do not infer use simply because a file exists.
191
+ - [ ] I06 Keep the session's trusted strategist performance state and each
192
+ run's recorded weights consistent through delta runs and replay.
193
+ - [ ] I07 Update README and quant help to describe the latest whole product,
194
+ preserving inherited capabilities and distinguishing deployed behavior from
195
+ planned V8 changes. Keep historical PRDs intact.
196
+
197
+ Gate: regression tests cover session creation/resume, YOLO entry, general and
198
+ specialized markets, traces, RAG, replay, package export, proposal state, and
199
+ support contexts without academic imports or a parallel V8 workflow.
200
+
201
+ ## Phase 6: UI
202
+
203
+ Primary modules: `web/static/index.html`, existing session/run payloads and
204
+ routes in `app.py`, and `tests/test_v611_web_ui.py`.
205
+
206
+ - [ ] U01 Retain the YOLO entry, session/run selection, Finley output, options
207
+ context, and download behavior; add Run, Routing Table, and Permissions views.
208
+ - [ ] U02 Render all running agents and dependency-based waiting states from
209
+ runtime records. Show result availability separately from execution status.
210
+ - [ ] U03 Show the active routing plan by default and an explicit full registry
211
+ view with inactivity reasons. Keep exact names, list dependencies, and scope enums.
212
+ - [ ] U04 Display per-agent ACL templates and resolved paths, input/output
213
+ references, baseline source, and published read-only state. Keep views read-only.
214
+ - [ ] U05 Show genuine no-trade/watch decisions and data/agent failures distinctly;
215
+ do not render a blocked dependency or pending analysis as a final market opinion.
216
+ - [ ] U06 Keep polling tied to the selected session/run. Preserve tab, selection,
217
+ and scroll; a live run cannot overwrite a prior replay view. Label unavailable
218
+ legacy routing/ACL information without filling it from current configuration.
219
+ - [ ] U07 Verify loading, empty session, failed refresh, absent replay,
220
+ unavailable options, partial results, and download in every terminal state.
221
+ - [ ] U08 Verify browser screenshots and interactions at 390 x 844 and
222
+ 1440 x 900: readable long paths, usable tables, keyboard controls, parallel
223
+ rows, and no overlap or hidden result text.
224
+
225
+ Gate: backend payload tests and browser interaction checks pass. A static
226
+ HTML preview alone does not verify runtime progress or replay behavior.
227
+
228
+ ## Phase 7: Release Verification
229
+
230
+ - [ ] V01 Run focused suites during each phase, then the full applicable quant,
231
+ provider, coordinator, RAG, session, Slack, and UI regression suites once the
232
+ migration is integrated. Record pre-existing unrelated failures separately.
233
+ - [ ] V02 Verify a build/package includes contracts and UI assets and starts
234
+ with the existing deployment configuration. Do not claim configured means
235
+ authenticated or provider-entitled until live requests verify it.
236
+ - [ ] V03 Verify live Slack YOLO for SPY and a general ticker through the same
237
+ migrated agent runtime: real data, real LLM reasoning where required, trace
238
+ usage, named failures when any, and useful Finley output in Slack.
239
+ - [ ] V04 Verify live UI baseline then delta in the same session, including
240
+ BTC options exclusion and a mixed general/specialized run. Confirm the
241
+ observed plan, parallel execution, and frozen tickers match the contract.
242
+ - [ ] V05 Verify two same-day runs, replay of the first, and downloaded inputs,
243
+ outputs, evidence ledger, and baseline references against each run record.
244
+ - [ ] V06 Verify a controlled unavailable-input or failed-agent case through
245
+ the product integration test setup. Do not deliberately break shared live
246
+ credentials to create a failure; distinguish this test from live success evidence.
247
+ - [ ] V07 After a requested HF deployment, record deployed commit, startup
248
+ status, live UI/Slack result, provider coverage/limitations, and download
249
+ integrity. An actual unmet input requirement remains a release blocker.
250
+
251
+ Release gate: every required function point has evidence at its intended level.
252
+ Mocked agents prove orchestration behavior only. Real LLM calls alone do not
253
+ prove valid data, correct reasoning, usable results, or complete integration.
254
+
255
+ ## Commit Boundaries
256
+
257
+ Prefer coherent commits for contracts, file/ACL enforcement, dependency
258
+ execution, fetch/context agents, specialized analysts, research/risk/strategy,
259
+ Publisher/support agents, product integration, UI, and verification/documentation.
260
+ Keep intermediate commits reviewable and avoid deploying partial migration.
261
+
262
+ ## Verification Record
263
+
264
+ Add entries as work is completed. Include function-point IDs, commit, actual
265
+ check, outcome, and remaining limitation; live checks also include run/session
266
+ IDs and deployment revision. This table starts empty because this document
267
+ does not represent executed implementation work.
268
+
269
+ | Function points | Commit | Verification and level | Result | Limitation or follow-up |
270
+ |---|---|---|---|---|