tighten implementation planning traceability

.beads/issues.jsonl

@@ -4,10 +4,10 @@
 {"_type":"issue","id":"islandflow-259.3","title":"Synthetic market-data phase 03: scenarios, labels, and expected outputs","description":"Implement deterministic scenario authoring, separate ground-truth labels, and expected-output manifests as described in docs/implementation/synthetic-market-data/03-scenarios-labels-expected-outputs.md. This phase is intentionally split into smaller child issues for reviewable PRs.","acceptance_criteria":"Scenario catalog covers representative institutional, retail-attention, event-noise, volatility, hedge, and negative/no-alert conditions; labels remain separate from emitted events; expected outputs include required/forbidden evidence and false-positive penalties; generated outputs are deterministic and reviewable.","spec_id":"docs/implementation/synthetic-market-data/03-scenarios-labels-expected-outputs.md","status":"open","priority":1,"issue_type":"feature","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:40Z","created_by":"dirtydishes","updated_at":"2026-06-16T17:38:40Z","labels":["phase","planning","synthetic-market-data"],"dependencies":[{"issue_id":"islandflow-259.3","depends_on_id":"islandflow-259","type":"parent-child","created_at":"2026-06-16T13:38:40Z","created_by":"dirtydishes","metadata":"{}"},{"issue_id":"islandflow-259.3","depends_on_id":"islandflow-zxh.2","type":"blocks","created_at":"2026-06-16T13:39:06Z","created_by":"dirtydishes","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0}
 {"_type":"issue","id":"islandflow-zxh.2","title":"Smart-flow phase 02: evidence clustering and features","description":"Implement evidence extraction, eligibility, clustering, and feature construction as described in docs/implementation/smart-money/02-evidence-clustering-features.md. The phase moves toward evidence clusters without overconfident participant claims.","acceptance_criteria":"Eligibility decisions, quote joins, evidence quality, clustering keys, and feature values are represented explicitly; ingest remains normalization-first; features preserve traceable evidence refs; stale/wide/noisy inputs can be rejected or down-weighted with reasons.","spec_id":"docs/implementation/smart-money/02-evidence-clustering-features.md","status":"open","priority":1,"issue_type":"feature","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:39Z","created_by":"dirtydishes","updated_at":"2026-06-16T17:38:39Z","labels":["phase","planning","smart-flow","smart-money"],"dependencies":[{"issue_id":"islandflow-zxh.2","depends_on_id":"islandflow-259.2","type":"blocks","created_at":"2026-06-16T13:39:05Z","created_by":"dirtydishes","metadata":"{}"},{"issue_id":"islandflow-zxh.2","depends_on_id":"islandflow-zxh","type":"parent-child","created_at":"2026-06-16T13:38:38Z","created_by":"dirtydishes","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0}
 {"_type":"issue","id":"islandflow-259.2","title":"Synthetic market-data phase 02: manifests, fixtures, and CLI","description":"Implement manifest, fixture, and CLI support for deterministic synthetic runs as described in docs/implementation/synthetic-market-data/02-manifests-fixtures-cli.md. The phase turns the deterministic engine into reusable test/demo artifacts.","acceptance_criteria":"CLI can generate fixtures and expected-output-ready manifests from seed bundles and profiles; manifests pin generator version, seed, parameter hash, event hashes, and replay ordering; fixture helpers support infra-free Bun tests; generated artifacts avoid embedding hidden labels in market events.","spec_id":"docs/implementation/synthetic-market-data/02-manifests-fixtures-cli.md","status":"open","priority":1,"issue_type":"feature","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:37Z","created_by":"dirtydishes","updated_at":"2026-06-16T17:38:37Z","labels":["phase","planning","synthetic-market-data"],"dependencies":[{"issue_id":"islandflow-259.2","depends_on_id":"islandflow-259","type":"parent-child","created_at":"2026-06-16T13:38:37Z","created_by":"dirtydishes","metadata":"{}"},{"issue_id":"islandflow-259.2","depends_on_id":"islandflow-zxh.1","type":"blocks","created_at":"2026-06-16T13:39:04Z","created_by":"dirtydishes","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0}
-{"_type":"issue","id":"islandflow-zxh.1","title":"Smart-flow phase 01: contracts and vocabulary","description":"Implement the contract and naming foundation described in docs/implementation/smart-money/01-contracts-vocabulary.md. The phase separates facts, evidence, hypotheses, confidence, abstention, and user-facing insight projections before classifier behavior is expanded.","acceptance_criteria":"Canonical contracts distinguish observations, evidence clusters, hypotheses, confidence vectors, abstention reasons, and insight projections; legacy smart-money naming is compatibility-only where needed; version fields are present; migration risks and aliases are documented.","spec_id":"docs/implementation/smart-money/01-contracts-vocabulary.md","status":"open","priority":1,"issue_type":"feature","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:36Z","created_by":"dirtydishes","updated_at":"2026-06-16T17:38:36Z","labels":["phase","planning","smart-flow","smart-money"],"dependencies":[{"issue_id":"islandflow-zxh.1","depends_on_id":"islandflow-259.1","type":"blocks","created_at":"2026-06-16T13:39:03Z","created_by":"dirtydishes","metadata":"{}"},{"issue_id":"islandflow-zxh.1","depends_on_id":"islandflow-zxh","type":"parent-child","created_at":"2026-06-16T13:38:35Z","created_by":"dirtydishes","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
+{"_type":"issue","id":"islandflow-zxh.1","title":"Smart-flow phase 01: contracts and vocabulary","description":"Implement the contract and naming foundation described in docs/implementation/smart-money/01-contracts-vocabulary.md. The phase separates facts, evidence, hypotheses, confidence, abstention, and user-facing insight projections before classifier behavior is expanded.","acceptance_criteria":"Canonical contracts distinguish observations, evidence clusters, hypotheses, confidence vectors, abstention reasons, and insight projections; legacy smart-money naming is compatibility-only where needed; version fields are present; migration risks and aliases are documented.","notes":"2026-06-16 planning QA: removed the dependency on islandflow-259.1. Smart-flow contracts/vocabulary can run in parallel with the synthetic deterministic spine as long as it aligns with existing canonical market event contracts and provenance assumptions.","spec_id":"docs/implementation/smart-money/01-contracts-vocabulary.md","status":"open","priority":1,"issue_type":"feature","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:36Z","created_by":"dirtydishes","updated_at":"2026-06-16T18:17:09Z","labels":["phase","planning","smart-flow","smart-money"],"dependencies":[{"issue_id":"islandflow-zxh.1","depends_on_id":"islandflow-zxh","type":"parent-child","created_at":"2026-06-16T13:38:35Z","created_by":"dirtydishes","metadata":"{}"}],"dependency_count":0,"dependent_count":1,"comment_count":0}
-{"_type":"issue","id":"islandflow-259.1","title":"Synthetic market-data phase 01: deterministic spine","description":"Implement the deterministic synthetic market-data foundation described in docs/implementation/synthetic-market-data/01-deterministic-spine.md. The phase extracts generation into a seeded package/API that emits canonical market events with provenance while keeping labels separate.","acceptance_criteria":"Seeded generation is byte/hash stable for fixed inputs; emitted events use canonical OptionPrint, OptionNBBO, EquityPrint, and EquityQuote contracts; provenance metadata includes run/seed/parameter context; hidden labels are not embedded in market events; early tests run without Docker, ClickHouse, NATS, or Redis.","spec_id":"docs/implementation/synthetic-market-data/01-deterministic-spine.md","status":"open","priority":1,"issue_type":"feature","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:34Z","created_by":"dirtydishes","updated_at":"2026-06-16T17:38:34Z","labels":["phase","planning","synthetic-market-data"],"dependencies":[{"issue_id":"islandflow-259.1","depends_on_id":"islandflow-259","type":"parent-child","created_at":"2026-06-16T13:38:33Z","created_by":"dirtydishes","metadata":"{}"}],"dependency_count":0,"dependent_count":1,"comment_count":0}
+{"_type":"issue","id":"islandflow-259.1","title":"Synthetic market-data phase 01: deterministic spine","description":"Implement the deterministic synthetic market-data foundation described in docs/implementation/synthetic-market-data/01-deterministic-spine.md. The phase extracts generation into a seeded package/API that emits canonical market events with provenance while keeping labels separate.","acceptance_criteria":"Seeded generation is byte/hash stable for fixed inputs; emitted events use canonical OptionPrint, OptionNBBO, EquityPrint, and EquityQuote contracts; provenance metadata includes run/seed/parameter context; hidden labels are not embedded in market events; early tests run without Docker, ClickHouse, NATS, or Redis.","spec_id":"docs/implementation/synthetic-market-data/01-deterministic-spine.md","status":"open","priority":1,"issue_type":"feature","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:34Z","created_by":"dirtydishes","updated_at":"2026-06-16T17:38:34Z","labels":["phase","planning","synthetic-market-data"],"dependencies":[{"issue_id":"islandflow-259.1","depends_on_id":"islandflow-259","type":"parent-child","created_at":"2026-06-16T13:38:33Z","created_by":"dirtydishes","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
-{"_type":"issue","id":"islandflow-zxh","title":"Plan smart-money to smart-flow implementation phases","description":"Track the phase-by-phase implementation plan split from docs/plans/smart-flow-architecture-review.md. Durable roadmap: docs/implementation/smart-money/00-roadmap.md. This epic covers evidence-backed smart-flow contracts, clustering, hypothesis scoring, replay evaluation, API/UI explainability, and future calibration.","acceptance_criteria":"Phase docs exist under docs/implementation/smart-money; child phase issues link to their docs; blocker dependencies reflect the planned implementation order; no application code is implemented as part of this planning epic.","notes":"2026-06-16 readable HTML pass: added docs/implementation/smart-money/index.html as a standalone, dark-mode readable companion covering the roadmap and all smart-flow phases. No application code changed.","spec_id":"docs/implementation/smart-money/00-roadmap.md","status":"in_progress","priority":1,"issue_type":"epic","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:32Z","created_by":"dirtydishes","updated_at":"2026-06-16T17:58:37Z","started_at":"2026-06-16T17:51:54Z","labels":["planning","smart-flow","smart-money"],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"islandflow-zxh","title":"Plan smart-money to smart-flow implementation phases","description":"Track the phase-by-phase implementation plan split from docs/plans/smart-flow-architecture-review.md. Durable roadmap: docs/implementation/smart-money/00-roadmap.md. This epic covers evidence-backed smart-flow contracts, clustering, hypothesis scoring, replay evaluation, API/UI explainability, and future calibration.","acceptance_criteria":"Phase docs exist under docs/implementation/smart-money; child phase issues link to their docs; blocker dependencies reflect the planned implementation order; no application code is implemented as part of this planning epic.","notes":"2026-06-16 readable HTML pass: added docs/implementation/smart-money/index.html as a standalone, dark-mode readable companion covering the roadmap and all smart-flow phases. No application code changed.\n2026-06-16 final planning QA: verified research -\u003e architecture plan -\u003e phase docs -\u003e Beads traceability for smart-flow phases; removed the unnecessary blocker on smart-flow phase 01 so it can run in parallel with synthetic phase 01.","spec_id":"docs/implementation/smart-money/00-roadmap.md","status":"in_progress","priority":1,"issue_type":"epic","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:32Z","created_by":"dirtydishes","updated_at":"2026-06-16T18:17:10Z","started_at":"2026-06-16T17:51:54Z","labels":["planning","smart-flow","smart-money"],"dependency_count":0,"dependent_count":0,"comment_count":0}
-{"_type":"issue","id":"islandflow-259","title":"Plan synthetic market-data implementation phases","description":"Track the phase-by-phase implementation plan split from docs/plans/synthetic-market-data-architecture-review.md. Durable roadmap: docs/implementation/synthetic-market-data/00-roadmap.md. This epic covers deterministic synthetic event generation with canonical market event types, separate labels/manifests, replay integration, demo/load profiles, and future historical calibration.","acceptance_criteria":"Phase docs exist under docs/implementation/synthetic-market-data; child phase issues link to their docs; blocker dependencies reflect the planned implementation order; no application code is implemented as part of this planning epic.","notes":"2026-06-16 readable HTML pass: added docs/implementation/synthetic-market-data/index.html as a standalone, dark-mode readable companion covering the roadmap and all synthetic phases. No application code changed.","spec_id":"docs/implementation/synthetic-market-data/00-roadmap.md","status":"in_progress","priority":1,"issue_type":"epic","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:30Z","created_by":"dirtydishes","updated_at":"2026-06-16T17:58:36Z","started_at":"2026-06-16T17:51:54Z","labels":["planning","synthetic-market-data"],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"islandflow-259","title":"Plan synthetic market-data implementation phases","description":"Track the phase-by-phase implementation plan split from docs/plans/synthetic-market-data-architecture-review.md. Durable roadmap: docs/implementation/synthetic-market-data/00-roadmap.md. This epic covers deterministic synthetic event generation with canonical market event types, separate labels/manifests, replay integration, demo/load profiles, and future historical calibration.","acceptance_criteria":"Phase docs exist under docs/implementation/synthetic-market-data; child phase issues link to their docs; blocker dependencies reflect the planned implementation order; no application code is implemented as part of this planning epic.","notes":"2026-06-16 readable HTML pass: added docs/implementation/synthetic-market-data/index.html as a standalone, dark-mode readable companion covering the roadmap and all synthetic phases. No application code changed.\n2026-06-16 final planning QA: verified research -\u003e architecture plan -\u003e phase docs -\u003e Beads traceability for synthetic market-data phases; added explicit research review links in phase docs and kept implementation scope phase-bounded.","spec_id":"docs/implementation/synthetic-market-data/00-roadmap.md","status":"in_progress","priority":1,"issue_type":"epic","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-06-16T17:38:30Z","created_by":"dirtydishes","updated_at":"2026-06-16T18:17:09Z","started_at":"2026-06-16T17:51:54Z","labels":["planning","synthetic-market-data"],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-0e3","title":"Fix PR 23 CI failures","description":"PR 23 is failing the Forgejo CI Validate workflow. Reproduce the failing gates locally, fix the underlying formatting/lint/typecheck/test/build issues, update the PR branch, and confirm the remote check passes.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-06-14T19:35:07Z","created_by":"dirtydishes","updated_at":"2026-06-14T19:37:01Z","started_at":"2026-06-14T19:35:12Z","closed_at":"2026-06-14T19:37:01Z","close_reason":"Local Validate workflow passes after applying formatter output and syncing the Docker workspace snapshot.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-9w7","title":"Allow local dev origins on hosted API","description":"Local bun run dev:web and desktop-local point at the hosted API, but browser requests from http://127.0.0.1:3000 are blocked because the API omits CORS headers and returns 404 for OPTIONS preflight. Add API-side CORS handling, validate local web/desktop browser access, and deploy the API fix.","acceptance_criteria":"API responses include Access-Control-Allow-Origin for allowed local/dev origins; OPTIONS preflight succeeds; bun run dev:web reaches hosted REST/WS endpoints from a browser; bun run dev:desktop local mode reaches the backend through the local web UI; tests/build pass; fix is deployed to api.flow.deltaisland.io.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-06-13T15:04:19Z","created_by":"dirtydishes","updated_at":"2026-06-13T15:29:42Z","started_at":"2026-06-13T15:04:26Z","closed_at":"2026-06-13T15:29:42Z","close_reason":"Hosted API now reflects allowed local dev origins and handles OPTIONS preflight; local web and desktop dev runners both reach https://api.flow.deltaisland.io; API tests, typecheck, and web build passed.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-xkq","title":"Rebuild production dashboard options news around mock9 aesthetic","description":"Reconstruct the production web UI for Dashboard, Options, and News around the mock9 through mock12 dense terminal aesthetic while preserving production data subscriptions, drawers, virtualization, route helpers, redirects, and validation.","status":"closed","priority":1,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-06-13T14:07:34Z","created_by":"dirtydishes","updated_at":"2026-06-13T14:26:46Z","started_at":"2026-06-13T14:07:53Z","closed_at":"2026-06-13T14:26:46Z","close_reason":"Rebuilt Dashboard, Options, and News around the dense mock9 to mock12 production aesthetic; tests and build passed, and Browser visual inspection was documented as blocked by the unavailable in-app browser backend.","dependency_count":0,"dependent_count":0,"comment_count":0}

docs/implementation/README.md

@@ -8,10 +8,12 @@ The architecture reviews in `docs/plans/` and research reports in `docs/research
 
 Use this precedence order when planning or implementing phase work:
 
-1. Beads issue
+1. Current Beads issue
-2. Phase document in `docs/implementation/`
+2. Referenced phase document under `docs/implementation/`
-3. Architecture plan in `docs/plans/`
+3. Architecture plan under `docs/plans/`
-4. Research report in `docs/research-docs/`
+4. Research report under `docs/research-docs/`
+
+This repository uses `docs/research-docs/` for research reports; `docs/research/` is not present.
 
 Research reports provide rationale and useful constraints. They do not add active implementation scope unless that scope is explicitly pulled into a phase document and Beads issue.
 
@@ -46,16 +48,16 @@ This is the intended MVP ordering. Future calibration phases sit after the MVP c
 
 | Order | Phase | Beads issue | Blocks next because |
 | ---: | --- | --- | --- |
-| 1 | Synthetic deterministic spine | `islandflow-259.1` | The smart-flow vocabulary needs stable raw event/provenance assumptions. |
+| 1A | Synthetic deterministic spine | `islandflow-259.1` | Establishes seeded raw event generation and provenance assumptions for later synthetic work. |
-| 2 | Smart-flow contracts and vocabulary | `islandflow-zxh.1` | Synthetic manifests should target the eventual evidence/hypothesis language. |
+| 1B | Smart-flow contracts and vocabulary | `islandflow-zxh.1` | Can safely run in parallel with synthetic phase 01; defines evidence/hypothesis language before scoring work. |
-| 3 | Synthetic manifests, fixtures, and CLI | `islandflow-259.2` | Evidence clustering needs deterministic fixtures before broad behavior changes. |
+| 2 | Synthetic manifests, fixtures, and CLI | `islandflow-259.2` | Evidence clustering needs deterministic fixtures before broad behavior changes. |
-| 4 | Smart-flow evidence clustering and features | `islandflow-zxh.2` | Scenario labels need the evidence vocabulary they are expected to exercise. |
+| 3 | Smart-flow evidence clustering and features | `islandflow-zxh.2` | Scenario labels need the evidence vocabulary they are expected to exercise. |
-| 5 | Synthetic scenarios, labels, and expected outputs | `islandflow-259.3` | Hypothesis scoring needs labeled positive, negative, and abstention cases. |
+| 4 | Synthetic scenarios, labels, and expected outputs | `islandflow-259.3` | Hypothesis scoring needs labeled positive, negative, and abstention cases. |
-| 6 | Smart-flow hypothesis scoring and abstention | `islandflow-zxh.3` | Synthetic replay integration should validate the derived hypothesis pipeline. |
+| 5 | Smart-flow hypothesis scoring and abstention | `islandflow-zxh.3` | Synthetic replay integration should validate the derived hypothesis pipeline. |
-| 7 | Synthetic replay integration | `islandflow-259.4` | Smart-flow golden tests need replayable synthetic runs. |
+| 6 | Synthetic replay integration | `islandflow-259.4` | Smart-flow golden tests need replayable synthetic runs. |
-| 8 | Smart-flow replay evaluation and golden tests | `islandflow-zxh.4` | Demos should wait until replay proves the semantics. |
+| 7 | Smart-flow replay evaluation and golden tests | `islandflow-zxh.4` | Demos should wait until replay proves the semantics. |
-| 9 | Synthetic demo and load profiles | `islandflow-259.5` | API/UI explainability should show stable, named, deterministic runs. |
+| 8 | Synthetic demo and load profiles | `islandflow-259.5` | API/UI explainability should show stable, named, deterministic runs. |
-| 10 | Smart-flow API/UI explainability | `islandflow-zxh.5` | This is the final MVP presentation layer after the evidence pipeline is validated. |
+| 9 | Smart-flow API/UI explainability | `islandflow-zxh.5` | This is the final MVP presentation layer after the evidence pipeline is validated. |
 
 ## Future Work
 

docs/implementation/smart-money/00-roadmap.md

@@ -23,7 +23,7 @@ The research documents are background and rationale only. Scope comes from the B
 
 | Phase | Beads issue | Depends on | Purpose |
 | --- | --- | --- | --- |
-| 01 - Contracts and vocabulary | `islandflow-zxh.1` | `islandflow-259.1` | Define evidence/hypothesis/insight contracts and retire canonical overconfidence. |
+| 01 - Contracts and vocabulary | `islandflow-zxh.1` | None; safe parallel with `islandflow-259.1` | Define evidence/hypothesis/insight contracts and retire canonical overconfidence. |
 | 02 - Evidence clustering and features | `islandflow-zxh.2` | `islandflow-259.2` | Extract eligibility, evidence facts, clusters, and traceable features. |
 | 03 - Hypothesis scoring and abstention | `islandflow-zxh.3` | `islandflow-259.3` | Score cautious hypotheses and represent abstention/alternatives. |
 | 04 - Replay evaluation and golden tests | `islandflow-zxh.4` | `islandflow-259.4` | Validate derived outputs through deterministic replay and golden fixtures. |

docs/implementation/smart-money/01-contracts-vocabulary.md

@@ -12,6 +12,7 @@ The current system has useful infrastructure but overconfident domain names. Bef
 
 - Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
 - Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+- Research architecture review copy: [`docs/research-docs/smart-flow-architecture-review.md`](../../research-docs/smart-flow-architecture-review.md)
 
 These documents are rationale, not added scope. This phase implements only vocabulary, contracts, versioning, and compatibility notes.
 
@@ -27,7 +28,7 @@ These documents are rationale, not added scope. This phase implements only vocab
 
 ## Dependencies on earlier phases
 
-- `islandflow-259.1` - Synthetic deterministic spine, so contract work can align with canonical raw event and provenance assumptions.
+None. This phase can safely run in parallel with `islandflow-259.1`; align on the existing canonical raw market event contracts and provenance assumptions, but do not wait for synthetic package implementation.
 
 ## Likely files/modules touched
 

docs/implementation/smart-money/02-evidence-clustering-features.md

@@ -12,6 +12,7 @@ Contracts alone do not change behavior. This phase gives the system a clean evid
 
 - Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
 - Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+- Research architecture review copy: [`docs/research-docs/smart-flow-architecture-review.md`](../../research-docs/smart-flow-architecture-review.md)
 
 These documents are rationale, not added scope. This phase implements only eligibility, evidence facts, clustering, and traceable features.
 

docs/implementation/smart-money/03-hypothesis-scoring-abstention.md

@@ -12,6 +12,7 @@ Scoring should wait until the system can represent evidence clearly and syntheti
 
 - Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
 - Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+- Research architecture review copy: [`docs/research-docs/smart-flow-architecture-review.md`](../../research-docs/smart-flow-architecture-review.md)
 
 These documents are rationale, not added scope. This phase implements only cautious hypothesis scoring, alternatives, penalties, and abstention.
 

docs/implementation/smart-money/04-replay-evaluation-golden-tests.md

@@ -12,6 +12,7 @@ Replay evaluation should come after synthetic replay can select stable runs and
 
 - Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
 - Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+- Research architecture review copy: [`docs/research-docs/smart-flow-architecture-review.md`](../../research-docs/smart-flow-architecture-review.md)
 - Synthetic research report: [`docs/research-docs/synthetic-market-data-generation.md`](../../research-docs/synthetic-market-data-generation.md)
 
 These documents are rationale, not added scope. This phase implements only deterministic replay evaluation and compact golden tests.

docs/implementation/smart-money/05-api-ui-explainability.md

@@ -12,6 +12,7 @@ The presentation layer should wait until contracts, evidence, scoring, and repla
 
 - Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
 - Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+- Research architecture review copy: [`docs/research-docs/smart-flow-architecture-review.md`](../../research-docs/smart-flow-architecture-review.md)
 
 These documents are rationale, not added scope. This phase implements only API, websocket, and UI explainability surfaces for validated outputs.
 

docs/implementation/smart-money/99-future-calibration.md

@@ -12,6 +12,7 @@ The architecture should leave room for calibration, but calibration should not b
 
 - Architecture plan: [`docs/plans/smart-flow-architecture-review.md`](../../plans/smart-flow-architecture-review.md)
 - Research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
+- Research architecture review copy: [`docs/research-docs/smart-flow-architecture-review.md`](../../research-docs/smart-flow-architecture-review.md)
 
 These documents are rationale, not added scope. This future phase is the place to turn research ideas into scoped calibration work after MVP.
 

docs/implementation/smart-money/index.html

@@ -486,7 +486,7 @@ tr:last-child td { border-bottom: 0; }
 <div class="table-wrap"><table>
 <thead><tr><th>Phase</th><th>Beads issue</th><th>Depends on</th><th>Purpose</th></tr></thead>
 <tbody>
-<tr><td>01 - Contracts and vocabulary</td><td><code>islandflow-zxh.1</code></td><td><code>islandflow-259.1</code></td><td>Define evidence/hypothesis/insight contracts and retire canonical overconfidence.</td></tr>
+<tr><td>01 - Contracts and vocabulary</td><td><code>islandflow-zxh.1</code></td><td>None; safe parallel with <code>islandflow-259.1</code></td><td>Define evidence/hypothesis/insight contracts and retire canonical overconfidence.</td></tr>
 <tr><td>02 - Evidence clustering and features</td><td><code>islandflow-zxh.2</code></td><td><code>islandflow-259.2</code></td><td>Extract eligibility, evidence facts, clusters, and traceable features.</td></tr>
 <tr><td>03 - Hypothesis scoring and abstention</td><td><code>islandflow-zxh.3</code></td><td><code>islandflow-259.3</code></td><td>Score cautious hypotheses and represent abstention/alternatives.</td></tr>
 <tr><td>04 - Replay evaluation and golden tests</td><td><code>islandflow-zxh.4</code></td><td><code>islandflow-259.4</code></td><td>Validate derived outputs through deterministic replay and golden fixtures.</td></tr>
@@ -529,6 +529,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/smart-flow-architecture-review.md">docs/plans/smart-flow-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/smart-flow-market-mechanics.md">docs/research-docs/smart-flow-market-mechanics.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/smart-flow-architecture-review.md">docs/research-docs/smart-flow-architecture-review.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This phase implements only vocabulary, contracts, versioning, and compatibility notes.</p>
 <h3 id="01-contracts-vocabulary-research-basis">Research basis</h3>
@@ -542,9 +543,7 @@ tr:last-child td { border-bottom: 0; }
 <li>Participant identity claims and research-grade calibration stay outside the vocabulary foundation.</li>
 </ul>
 <h3 id="01-contracts-vocabulary-dependencies-on-earlier-phases">Dependencies on earlier phases</h3>
-<ul>
+<p>None. This phase can safely run in parallel with <code>islandflow-259.1</code>; align on the existing canonical raw market event contracts and provenance assumptions, but do not wait for synthetic package implementation.</p>
-<li><code>islandflow-259.1</code> - Synthetic deterministic spine, so contract work can align with canonical raw event and provenance assumptions.</li>
-</ul>
 <h3 id="01-contracts-vocabulary-likely-files-modules-touched">Likely files/modules touched</h3>
 <ul>
 <li><code>packages/types/src/events.ts</code></li>
@@ -613,6 +612,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/smart-flow-architecture-review.md">docs/plans/smart-flow-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/smart-flow-market-mechanics.md">docs/research-docs/smart-flow-market-mechanics.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/smart-flow-architecture-review.md">docs/research-docs/smart-flow-architecture-review.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This phase implements only eligibility, evidence facts, clustering, and traceable features.</p>
 <h3 id="02-evidence-clustering-features-research-basis">Research basis</h3>
@@ -700,6 +700,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/smart-flow-architecture-review.md">docs/plans/smart-flow-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/smart-flow-market-mechanics.md">docs/research-docs/smart-flow-market-mechanics.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/smart-flow-architecture-review.md">docs/research-docs/smart-flow-architecture-review.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This phase implements only cautious hypothesis scoring, alternatives, penalties, and abstention.</p>
 <h3 id="03-hypothesis-scoring-abstention-research-basis">Research basis</h3>
@@ -788,6 +789,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/smart-flow-architecture-review.md">docs/plans/smart-flow-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/smart-flow-market-mechanics.md">docs/research-docs/smart-flow-market-mechanics.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/smart-flow-architecture-review.md">docs/research-docs/smart-flow-architecture-review.md</a></li>
 <li>Synthetic research report: <a href="../../research-docs/synthetic-market-data-generation.md">docs/research-docs/synthetic-market-data-generation.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This phase implements only deterministic replay evaluation and compact golden tests.</p>
@@ -876,6 +878,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/smart-flow-architecture-review.md">docs/plans/smart-flow-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/smart-flow-market-mechanics.md">docs/research-docs/smart-flow-market-mechanics.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/smart-flow-architecture-review.md">docs/research-docs/smart-flow-architecture-review.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This phase implements only API, websocket, and UI explainability surfaces for validated outputs.</p>
 <h3 id="05-api-ui-explainability-research-basis">Research basis</h3>
@@ -966,6 +969,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/smart-flow-architecture-review.md">docs/plans/smart-flow-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/smart-flow-market-mechanics.md">docs/research-docs/smart-flow-market-mechanics.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/smart-flow-architecture-review.md">docs/research-docs/smart-flow-architecture-review.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This future phase is the place to turn research ideas into scoped calibration work after MVP.</p>
 <h3 id="99-future-calibration-research-basis">Research basis</h3>

docs/implementation/synthetic-market-data/01-deterministic-spine.md

@@ -12,6 +12,7 @@ Everything else depends on reproducible raw events. Manifests, labels, replay, d
 
 - Architecture plan: [`docs/plans/synthetic-market-data-architecture-review.md`](../../plans/synthetic-market-data-architecture-review.md)
 - Research report: [`docs/research-docs/synthetic-market-data-generation.md`](../../research-docs/synthetic-market-data-generation.md)
+- Research architecture review copy: [`docs/research-docs/synthetic-data-architecture-review.md`](../../research-docs/synthetic-data-architecture-review.md)
 
 These documents are rationale, not added scope. This phase implements only the deterministic spine described below.
 

docs/implementation/synthetic-market-data/02-manifests-fixtures-cli.md

@@ -12,6 +12,7 @@ The deterministic spine gives the repo stable raw events. The next step is to ma
 
 - Architecture plan: [`docs/plans/synthetic-market-data-architecture-review.md`](../../plans/synthetic-market-data-architecture-review.md)
 - Research report: [`docs/research-docs/synthetic-market-data-generation.md`](../../research-docs/synthetic-market-data-generation.md)
+- Research architecture review copy: [`docs/research-docs/synthetic-data-architecture-review.md`](../../research-docs/synthetic-data-architecture-review.md)
 
 These documents are rationale, not added scope. This phase implements only manifests, fixtures, and CLI support.
 

docs/implementation/synthetic-market-data/03-scenarios-labels-expected-outputs.md

@@ -12,6 +12,7 @@ The generator and manifest layers should exist before scenario authoring. Smart-
 
 - Architecture plan: [`docs/plans/synthetic-market-data-architecture-review.md`](../../plans/synthetic-market-data-architecture-review.md)
 - Research report: [`docs/research-docs/synthetic-market-data-generation.md`](../../research-docs/synthetic-market-data-generation.md)
+- Research architecture review copy: [`docs/research-docs/synthetic-data-architecture-review.md`](../../research-docs/synthetic-data-architecture-review.md)
 - Smart-flow research report: [`docs/research-docs/smart-flow-market-mechanics.md`](../../research-docs/smart-flow-market-mechanics.md)
 
 These documents are rationale, not added scope. This phase implements only named scenarios, separate labels, and expected-output contracts.

docs/implementation/synthetic-market-data/04-replay-integration.md

@@ -12,6 +12,7 @@ Replay should not be wired to synthetic data until the generator, manifests, lab
 
 - Architecture plan: [`docs/plans/synthetic-market-data-architecture-review.md`](../../plans/synthetic-market-data-architecture-review.md)
 - Research report: [`docs/research-docs/synthetic-market-data-generation.md`](../../research-docs/synthetic-market-data-generation.md)
+- Research architecture review copy: [`docs/research-docs/synthetic-data-architecture-review.md`](../../research-docs/synthetic-data-architecture-review.md)
 
 These documents are rationale, not added scope. This phase implements only deterministic synthetic replay integration.
 

docs/implementation/synthetic-market-data/05-demo-load-profiles.md

@@ -12,6 +12,7 @@ Demos are useful only after the underlying data can be trusted. This phase delib
 
 - Architecture plan: [`docs/plans/synthetic-market-data-architecture-review.md`](../../plans/synthetic-market-data-architecture-review.md)
 - Research report: [`docs/research-docs/synthetic-market-data-generation.md`](../../research-docs/synthetic-market-data-generation.md)
+- Research architecture review copy: [`docs/research-docs/synthetic-data-architecture-review.md`](../../research-docs/synthetic-data-architecture-review.md)
 
 These documents are rationale, not added scope. This phase implements only named deterministic demo and load profiles.
 

docs/implementation/synthetic-market-data/99-future-historical-calibration.md

@@ -12,6 +12,7 @@ It is useful to name the future work now so early designs keep calibration hooks
 
 - Architecture plan: [`docs/plans/synthetic-market-data-architecture-review.md`](../../plans/synthetic-market-data-architecture-review.md)
 - Research report: [`docs/research-docs/synthetic-market-data-generation.md`](../../research-docs/synthetic-market-data-generation.md)
+- Research architecture review copy: [`docs/research-docs/synthetic-data-architecture-review.md`](../../research-docs/synthetic-data-architecture-review.md)
 
 These documents are rationale, not added scope. This future phase is the place to turn research ideas into scoped calibration work after MVP.
 

docs/implementation/synthetic-market-data/index.html

@@ -525,6 +525,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/synthetic-market-data-architecture-review.md">docs/plans/synthetic-market-data-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/synthetic-market-data-generation.md">docs/research-docs/synthetic-market-data-generation.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/synthetic-data-architecture-review.md">docs/research-docs/synthetic-data-architecture-review.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This phase implements only the deterministic spine described below.</p>
 <h3 id="01-deterministic-spine-research-basis">Research basis</h3>
@@ -609,6 +610,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/synthetic-market-data-architecture-review.md">docs/plans/synthetic-market-data-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/synthetic-market-data-generation.md">docs/research-docs/synthetic-market-data-generation.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/synthetic-data-architecture-review.md">docs/research-docs/synthetic-data-architecture-review.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This phase implements only manifests, fixtures, and CLI support.</p>
 <h3 id="02-manifests-fixtures-cli-research-basis">Research basis</h3>
@@ -695,6 +697,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/synthetic-market-data-architecture-review.md">docs/plans/synthetic-market-data-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/synthetic-market-data-generation.md">docs/research-docs/synthetic-market-data-generation.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/synthetic-data-architecture-review.md">docs/research-docs/synthetic-data-architecture-review.md</a></li>
 <li>Smart-flow research report: <a href="../../research-docs/smart-flow-market-mechanics.md">docs/research-docs/smart-flow-market-mechanics.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This phase implements only named scenarios, separate labels, and expected-output contracts.</p>
@@ -785,6 +788,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/synthetic-market-data-architecture-review.md">docs/plans/synthetic-market-data-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/synthetic-market-data-generation.md">docs/research-docs/synthetic-market-data-generation.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/synthetic-data-architecture-review.md">docs/research-docs/synthetic-data-architecture-review.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This phase implements only deterministic synthetic replay integration.</p>
 <h3 id="04-replay-integration-research-basis">Research basis</h3>
@@ -872,6 +876,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/synthetic-market-data-architecture-review.md">docs/plans/synthetic-market-data-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/synthetic-market-data-generation.md">docs/research-docs/synthetic-market-data-generation.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/synthetic-data-architecture-review.md">docs/research-docs/synthetic-data-architecture-review.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This phase implements only named deterministic demo and load profiles.</p>
 <h3 id="05-demo-load-profiles-research-basis">Research basis</h3>
@@ -960,6 +965,7 @@ tr:last-child td { border-bottom: 0; }
 <ul>
 <li>Architecture plan: <a href="../../plans/synthetic-market-data-architecture-review.md">docs/plans/synthetic-market-data-architecture-review.md</a></li>
 <li>Research report: <a href="../../research-docs/synthetic-market-data-generation.md">docs/research-docs/synthetic-market-data-generation.md</a></li>
+<li>Research architecture review copy: <a href="../../research-docs/synthetic-data-architecture-review.md">docs/research-docs/synthetic-data-architecture-review.md</a></li>
 </ul>
 <p>These documents are rationale, not added scope. This future phase is the place to turn research ideas into scoped calibration work after MVP.</p>
 <h3 id="99-future-historical-calibration-research-basis">Research basis</h3>