Specify ADAQ's fifteen-gate User-gated delivery sequence

[tonywxx]

Problem Statement

ADAQ's development history allowed planning systems, closed issues, reusable cores, green checks, and downstream implementation to outrun the executable product journey. The current recovery map groups multiple research stages into broad gates and exposes Paper work as the live frontier even though Market Data Acquisition, data validation and publication, Feature Engineering, Factor Steps 1–3, and Model Steps 4–6 have not each received current-head Workflow Module Acceptance and explicit User Workflow Continuation Approval.

The User needs one unambiguous delivery authority that starts with trustworthy OKX Spot Source evidence, advances only through accepted predecessor outputs, preserves useful existing implementation without treating it as accepted, and stops after every module for User verification. The final product must also integrate system-wide operational evidence before presenting a global Dashboard, without making logs, projections, frontend state, or issue closure authoritative.

Solution

Replace the active R1–R14 recovery order with one canonical fifteen-gate Workflow Delivery Sequence for the OKX-only V1 scope. The sequence contains three Workflow Foundations, the ten numbered Research-to-Paper Steps, Operational Observability and Monitoring, and the System Dashboard.

Each gate is represented by a Gate Parent issue. A Gate Parent owns independently actionable implementation children, but only children of the current User-authorized gate may be created or executed. Each child runs in one fresh /implement <issue> session. Completing children does not close the Gate Parent: the gate closes only after current-head evidence satisfies its acceptance contract and the User explicitly grants Workflow Continuation Approval.

The gates are:

Gate	Product Module	Gate Scope	Required accepted input	Primary accepted output
1	Data Foundation	Market Data Acquisition	Host-verified User and authorized OKX provider boundary	Acquisition Operation, Provider Capability evidence, immutable Source Market Dataset
2	Data Foundation	Data Validation, Canonicalization, Quality, and Persistence	Accepted immutable Source evidence from Gate 1	Canonical Market Dataset, Data Quality Report, published Market Data Snapshot, Point-in-Time Instrument Universe
3	Feature Engineering	Feature Engineering	Accepted Snapshot and Point-in-Time Universe from Gate 2	Frozen Feature Plan, fitting evidence where required, immutable Feature Dataset
4	Factor Research	Factor Step 1 — Discover Factors	Accepted Feature Dataset from Gate 3	Factor Candidate and immutable Factor Dataset
5	Factor Research	Factor Step 2 — Evaluate and Promote Factors	Accepted Factor Candidate and Dataset from Gate 4	Factor Evaluation Report and Factor Promotion Decision
6	Factor Research	Factor Step 3 — Qualify, Package, and Import Factor	Accepted Component-eligible Factor decision from Gate 5	Qualified Factor Package and Component Library record
7	Model Research	Model Step 4 — Train Model	Accepted Feature and promoted Factor evidence from Gates 3–6	retained Model Trials and selected immutable Model Artifact
8	Model Research	Model Step 5 — Evaluate Model	Accepted Model Trials and Artifact from Gate 7	Parameter Selection evidence and disjoint Final Evaluation Report
9	Model Research	Model Step 6 — Qualify Model Deployment	Accepted Model Artifact and evaluation evidence from Gate 8	Qualified Model Component or explicit Local Runtime Qualification
10	Strategy	Strategy Step 7 — Build Strategy	Accepted qualified Factor and Model inputs from Gates 6 and 9	frozen Strategy Candidate and Revision
11	Strategy	Strategy Step 8 — Backtest, Validate, and Qualify Strategy	Accepted Strategy Candidate from Gate 10	immutable Backtest and Validation evidence plus Qualified Strategy Package
12	Paper Operations	Paper Step 9 — Prepare Paper Account and Deploy Bot	Accepted qualified deployment inputs from Gate 11	secure OKX Demo Account, immutable Bot Deployment Bundle, first safe Running Runtime Attempt
13	Paper Operations	Paper Step 10 — Operate, Reconcile, and Review	Accepted Running Attempt and Paper authority from Gate 12	retained Orders, Fills, reconciliation evidence, Paper Feedback, and Research Review Decision
14	Operational Observability	Operational Observability and Monitoring	Typed operational evidence emitted by Gates 1–13	correlated Operational Events, Diagnostic Logs, Operational Metrics, Health Projections, Alerts, and Monitoring Safety Actions
15	System Dashboard	System Dashboard	Accepted monitoring projections and owning-domain evidence from Gate 14	localized, authorized, rebuildable global Dashboard and evidence drill-down

Gate 15 is followed by the human Readiness Assertion review that closes the canonical map. Readiness is not a sixteenth development gate.

User Stories

1. As an ADAQ User, I want one visible delivery sequence, so that I always know which module is authorized now.
2. As an ADAQ User, I want downstream modules paused until I approve their predecessor, so that incomplete evidence cannot be mistaken for progress.
3. As an ADAQ User, I want existing implementation preserved as candidate evidence, so that recovery does not waste working code.
4. As an ADAQ User, I want historical issue closure separated from current Module Acceptance, so that old comments cannot authorize new work.
5. As a researcher, I want Market Data Acquisition to stop at immutable Source evidence, so that acquisition cannot silently certify its own data quality.
6. As a researcher, I want to inspect OKX Provider Capability evidence and Source provenance, so that I know what was actually retrieved.
7. As a researcher, I want acquisition cancellation, retry, continuation, and Host restart behavior retained, so that interrupted collection remains auditable.
8. As a researcher, I want invalid Source evidence rejected by the next gate, so that Canonical Market Data is never inferred from provider success alone.
9. As a researcher, I want validation, canonicalization, quality, persistence, Snapshot publication, and Universe publication owned together, so that the data trust boundary has one acceptance decision.
10. As a researcher, I want every published Snapshot and Point-in-Time Universe to cite accepted Source evidence, so that later research has exact lineage.
11. As a researcher, I want Feature Engineering to consume only an accepted Snapshot and Universe, so that Feature evidence cannot precede its market context.
12. As a researcher, I want Feature Plans, fitted transformations, availability, warmup, and missingness frozen, so that Feature Datasets are causal and reproducible.
13. As a factor researcher, I want Factor discovery separated from evaluation, so that candidate creation does not imply research validity.
14. As a factor researcher, I want promotion to cite exact evaluation evidence, so that high historical scores do not become automatic authority.
15. As a factor researcher, I want qualification, packaging, and import completed inside Factor Step 3, so that Model research receives an actually eligible Factor input.
16. As a model researcher, I want training to retain exact Trials and Artifacts, so that evaluation can reproduce what was trained.
17. As a model researcher, I want Selection and Final Evaluation evidence separated, so that model choice does not leak final results.
18. As a model researcher, I want deployment qualification to distinguish portable Components from Local Runtime Qualification, so that unsupported deployment profiles are not fabricated.
19. As a strategy researcher, I want Strategy construction to consume accepted Factor and Model inputs, so that a Strategy cannot bind opaque or unqualified evidence.
20. As a strategy researcher, I want backtest, validation, and qualification completed before Paper deployment, so that a reusable core is not mistaken for a deployable Strategy.
21. As a Paper operator, I want only an OKX Demo Account accepted in V1, so that no Live endpoint or real-money authority can enter the workflow.
22. As a Paper operator, I want credentials held behind Host and operating-system authority, so that they never enter frontend state, evidence stores, Components, Workers, or logs.
23. As a Paper operator, I want Step 9 to reach a real first safe Running Attempt, so that account creation alone cannot satisfy deployment.
24. As a Paper operator, I want orders, fills, uncertain outcomes, stops, restarts, and reconciliation retained, so that Paper operation is recoverable and auditable.
25. As a researcher, I want Paper feedback followed by an explicit Research Review Decision, so that realized results create new research lineage rather than mutating a running deployment.
26. As an operator, I want every producing module to emit typed operational evidence at its own boundary, so that monitoring does not reconstruct missing facts later.
27. As an operator, I want network, provider, data, research, Paper, Bot, Worker, account, Risk, OMS, Adapter, storage, and local-system conditions monitored independently, so that one healthy summary cannot hide a critical dependency.
28. As an operator, I want Diagnostic Logs bounded and redacted, so that troubleshooting does not leak credentials, tokens, provider payloads, or private paths.
29. As an operator, I want Alerts and Monitoring Safety Actions tied to exact evidence, so that fail-closed responses are explainable and retained.
30. As an operator, I want the System Dashboard to show authorized global information and drill-down links, so that I can inspect the whole system without learning every workspace first.
31. As an operator, I want Dashboard actions routed to owning workspaces, so that a read projection never becomes trading or evidence authority.
32. As a bilingual User, I want every gate accepted in en-US and zh-CN, so that localization is part of the product contract rather than final polish.
33. As a User on a supported platform, I want automated evidence for every gate and platform-sensitive manual evidence where required, so that one machine's success is not generalized silently.
34. As an Acceptance Reviewer, I want every Gate Parent to bind exact current-head evidence, platform, locale, limitations, and reviewed upstream identity, so that approval has a declared scope.
35. As an Acceptance Reviewer, I want implementation agents prohibited from self-approving a Gate, so that only my explicit decision unlocks the next module.
36. As an Acceptance Reviewer, I want a changed output contract to reopen the affected gate and pause its downstream suffix, so that stale acceptance cannot survive semantic drift.
37. As an implementer, I want current-head gap analysis before tickets are created, so that already-satisfied behavior receives verification instead of duplicate code.
38. As an implementer, I want each implementation child small enough for one fresh /implement session, so that changes remain reviewable and independently evidenced.
39. As a tracker reader, I want the canonical map, Gate Parents, and implementation children to have distinct roles, so that planning state cannot be confused with execution state.
40. As a tracker reader, I want old recovery issues retained and explicitly mapped as historical evidence, so that useful decisions remain discoverable without appearing executable.
41. As a Release Owner, I want final Readiness Assertions to review the accepted fifteen-gate journey, so that Dashboard completion alone cannot claim V1 readiness.

Implementation Decisions

• V1 remains the complete local bilingual OKX Spot to OKX Demo Paper workflow. China A-share and U.S. equity support remain Post-V1 Market Expansion; Live endpoints, real credentials, and real-money submission remain prohibited.
• The Workflow Delivery Sequence is strictly serial. A gate consumes the exact accepted output of its predecessor and cannot be authorized by issue state, CI, fixture evidence, reusable cores, or an implementation agent.
• The canonical tracker hierarchy is one map, fifteen Gate Parent issues, and independently actionable implementation children. Gate Parents are planning and acceptance authorities, not /implement targets.
• All fifteen Gate Parents may exist for visibility. Detailed children are created only for the current User-authorized gate through /to-spec and /to-tickets, based on current-head gaps.
• Market Data Acquisition owns provider interaction and immutable Source evidence only. It does not own validation, canonicalization, quality decisions, Snapshot publication, or Universe publication.
• Gate 2 owns the complete Source-to-published-market-evidence trust boundary. It must reject incomplete, stale, mixed, inaccessible, or incompatible Source evidence rather than granting readiness.
• Factor, Model, and Strategy qualification remain inside Steps 3, 6, and 8. Existing shared Component generation and qualification cores may be reused, but there is no cross-product qualification gate that jumps over research order.
• Model qualification preserves truthful deployment profiles. Portable Component qualification and Local Runtime Qualification remain distinct outcomes.
• Paper Step 9 includes the secure Account, Risk/OMS, immutable Bundle, deployment, supervision prerequisites, and first safe Running Attempt. Account setup alone is insufficient.
• Paper Step 10 owns Paper operation, uncertain outcomes, reconciliation, immutable feedback, and human review. It emits operational evidence but does not own system-wide monitoring.
• Every module emits typed operational evidence at its own boundary. Gate 14 correlates producer-owned Operational Events, Diagnostic Logs, Operational Metrics, Health Projections, Alerts, and Safety Actions; it does not invent missing evidence or replace owning-domain authority.
• Gate 15 is a rebuildable, authorized read projection. It displays global information and links to owning workspaces for evidence and actions; frontend state never grants trading, reconciliation, lifecycle, or readiness authority.
• No generic persisted workflow project, global completion percentage, second evidence store, or parallel planning authority is introduced. Gate progress is tracker and acceptance state; runtime state remains in its owning domain.
• Each Gate Parent remains open after its children finish. It closes only after criterion-level current-head evidence is recorded and the User grants explicit Workflow Continuation Approval.
• Every Gate Parent records: exact upstream identity; acceptance-criterion mapping; automated evidence; desktop product-run evidence; applicable cancellation, failure, retry, restart, recovery, and fail-closed evidence; security boundaries; both Interface Locales; supported-platform scope; limitations; reviewed commit; and User approval.
• Automated checks run on every declared supported platform for every gate. Routine manual acceptance uses the current primary platform; platform-sensitive gates and final acceptance require the full declared-platform manual matrix.
• A change to an accepted output contract, identity, data semantic, or evidence boundary reopens the affected Gate Parent and pauses its downstream suffix. A boundary-preserving internal change requires scoped impact analysis and fresh regression evidence rather than an automatic full restart.
• The current canonical recovery map is rewritten during /to-tickets, not during this spec step. Its former R1–R14 graph is retained in a historical mapping section.
• Closed recovery issues remain closed and become cited candidate evidence only. Open downstream recovery issues remain non-executable, lose any active frontier status, and are reattached to the appropriate future gate with native blockers; a genuinely conflicting or duplicate issue is closed as superseded, never deleted.
• Final Readiness Assertions review the accepted fifteen-gate journey and close the canonical map. They do not form a sixteenth development gate.
• The delivery workflow remains /grill-with-docs → /to-spec → /to-tickets → one fresh /implement <issue> session per implementation child. Planning completion never authorizes implementation.

Testing Decisions

• The highest acceptance seam for every gate is one external, bilingual Desktop product run that begins with the exact accepted upstream identity and ends with the gate's declared immutable output. Tests should assert visible behavior and retained evidence, not component internals.
• Existing Host command, lifecycle, persistence, engine, workspace, and end-to-end seams are preferred. A new lower-level seam is added only when required failure behavior cannot be observed reliably through an existing higher seam.
• Gate 1 reuses Provider capability, acquisition lifecycle, Source evidence, Data Foundation workspace, cancellation/retry/restart, pagination, and localization seams. It explicitly excludes Canonicalization, Quality, Snapshot, and Universe assertions, which belong to Gate 2.
• Gate 2 tests valid and invalid Source evidence through the complete publication boundary, including quarantine, gaps, quality, revisions, persistence, restart, Snapshot identity, Universe identity, and rejection of stale, mixed, inaccessible, or incomplete inputs.
• Gate 3 tests deterministic Feature evidence at the engine and workspace boundaries with exact Snapshot, Universe, Plan, engine identity, parameters, seed, availability, warmup, missing-input, cancellation, retry, and restart evidence.
• Factor, Model, and Strategy gates test each externally visible research transition separately: creation, evaluation/decision, and qualification. A high score, artifact existence, package build, or historical issue closure cannot stand in for the next transition.
• Paper gates test only OKX Demo behavior and must prove that Live endpoints and real-money authority are unreachable. Required seams cover secrets, connection, account snapshots, Risk/OMS, Bundle deployment, lifecycle control, orders/fills, uncertain outcomes, restart, reconciliation, feedback, and human review.
• Gate 14 tests producer-to-projection correlation across all declared Health Dimensions, including redaction, retention, alert lifecycle, debounce/hysteresis where applicable, Unknown states, and exact fail-closed Safety Actions.
• Gate 15 tests immediate semantic paint, independent projection loading, authorized global summaries, evidence drill-down, stale-state behavior, accessibility, both locales, and the absence of Dashboard-owned operational authority.
• Every Gate Parent includes the smallest applicable failure/recovery matrix rather than mechanically copying irrelevant scenarios. Cancellation or retry is required only for operations that support those transitions; missing, stale, incompatible, unauthorized, and uncertain inputs always fail closed where they affect authority.
• Current-head evidence is mandatory. Historical tests, comments, fixtures, and closed issues may identify prior art but satisfy a criterion only when fresh impact analysis and verification show that the behavior still holds.
• All declared supported platforms receive automated checks per gate. Platform-sensitive behavior and final acceptance receive manual evidence across the full declared platform matrix; ordinary gate-level manual acceptance uses the primary platform and records that scope explicitly.
• A good implementation child test fails when its externally observable acceptance behavior regresses and remains insensitive to internal refactoring. The ticketing step must avoid parallel test suites that prove the same behavior at multiple layers without a distinct risk.
• Gate 1 ticketing begins with a current-head gap audit across six candidate seams: Provider/User/Secret authority; Acquisition Operation and Source identity; Instrument Master and Trading Calendar acquisition; Closed-Bar backfill and continuation; cancellation/retry/resume/restart retention; and bilingual acquisition GUI inspection. Satisfied seams receive evidence, not duplicate implementation tickets.

Out of Scope

• Implementing any gate or implementation child as part of this specification.
• Rewriting the canonical map, publishing Gate Parents, changing native dependencies, or migrating old recovery issues before /to-tickets.
• Creating detailed children for downstream gates before the User authorizes those gates.
• Deleting historical issues or treating their closed state as current Module Acceptance.
• Rebuilding accepted cores solely to make new tickets appear active.
• China A-share or U.S. equity V1 provider, product, Paper, or readiness work.
• Live Trading, real-money orders, cloud Bot control, Marketplace infrastructure, or a public Unified Data/Trading API.
• A generic workflow database, mutable global progress record, second operational evidence store, frontend authority, or Dashboard-owned control plane.
• Automatic research promotion, model or strategy replacement, autonomous deployment, or hot-patching a running Bot.
• A sixteenth development gate for release review; final Readiness Assertions are human review of the accepted fifteen-gate journey.
• planning-with-files, repository-root planning scratch files, or another planning workflow alongside the Matt skills sequence.

Further Notes

• ADRs 0090–0092 and the domain glossary are authoritative for V1 scope, terminology, ordering, acceptance, Monitoring, and Dashboard authority.
• The existing R1–R14 recovery graph and its children remain valuable implementation and decision history, but their current tracker state is not an executable frontier under this specification.
• /to-tickets must preserve one canonical map, publish fifteen serial Gate Parents with native blocked_by edges, retain a historical recovery mapping, freeze open downstream work, and create detailed children only for Gate 1 after current-head gap analysis.
• After /to-tickets, the User selects the first Gate 1 implementation child in a fresh /implement <issue> session. Publishing the plan does not grant implementation authority.