V2.10.S3: Qt build POC

[deeprnd]

V2.10.S3: Qt build POC

Status: Backlog
Epic: #[github-epic-issue]
Parent roadmap item: V2.10: Build System Consolidation And Qt Build Validation
Labels: type/story, area/platform

Create a minimal Qt 6 CMake-based build that compiles the terminal scaffolding
described in doc/strategy/roadmap/epics/v3.19.md so V3.19 terminal development
has a proven build foundation before starting full QML/terminal implementation.

Product Outcome

The terminal scaffolding builds through a CMake-based just recipe on at least
Linux x86, confirming the Qt 6 path works before V3.19 invests effort in QML
pages, API clients, and investment flows.

User Story

As a terminal developer working on V3.19, I want to run just build-tkni and
get a compiled terminal binary, so that I can start adding QML pages and C++
models without first solving the build-system integration myself.

Scope

• In scope: create src/tickoni/terminal/CMakeLists.txt that finds Qt 6
  components (Quick, Quick Controls 2, Network) and compiles the scaffolding.
• In scope: create src/tickoni/terminal/app/main.cpp — a minimal Qt
  application entry point that initializes the QML engine and loads Main.qml.
• In scope: create src/tickoni/terminal/app/ApplicationController.cpp/.h
  — stub application controller class (not fully implemented, just compiles).
• In scope: create src/tickoni/terminal/api/ApiTypes.cpp/.h — stub API type
  definitions for the InvestmentCaseView conceptual response.
• In scope: create src/tickoni/terminal/commands/CommandRegistry.cpp/.h
  — stub command registry class.
• in scope: create src/tickoni/terminal/qml/Tickoni/Main.qml — a dark shell
  QML file matching the Midnight Oni color scheme from v3.19 with a title bar
  showing function mnemonics and a status strip.
• in scope: create src/tickoni/terminal/qml/Tickoni/style/Colors.qml — QML
  color palette constants from v3.19 (Carbon black, Midnight navy, Oni blue,
  etc.).
• in scope: add just build-tkni recipe that invokes CMake to build the Qt
  terminal.
• in scope: confirm the binary launches on Linux x86 (shows dark shell, no
  crash).
• in scope: add just build-tkni and just test-tkni entries to the
  justfile naming grid alongside existing build-tk / test-unit-tk etc.
• Out of scope: full QML page implementation (V3.19 story).
• Out of scope: real tkapi HTTP/WebSocket client (V3.19 story).
• Out of scope: actual investment flow logic (V3.19 story).
• Out of scope: macOS and Windows Qt build validation (deferred to V3.19 or
  a follow-up story).
• Out of scope: Qt packaging for Linux/macOS/Windows (deferred to V3.23).

Preconditions And Assumptions

• Qt 6 is available on the developer's Linux x86 environment (or can be
  installed via just setup-linux-x86 once S5 is done, but this story does
  not depend on S5 — the developer installs Qt manually).
• V3.19 defines the source layout, color scheme, visual identity, and
  conceptual API response for the terminal. This story implements the minimum
  to prove the build path works.
• build.zig is not involved — Qt is a separate CMake build tree under
  src/tickoni/terminal/.

Acceptance Criteria

• Given a Linux x86 environment with Qt 6 installed, when just build-tkni
  is run, then CMake configures successfully, compiles all C++ sources,
  and links a Qt 6 terminal binary at build/tickoni-terminal (or a
  documented output path).
• Given the compiled binary, when it is launched, then it starts the Qt
  QML engine and renders Main.qml with the dark shell and Midnight Oni
  color scheme without crashing.
• CMakeLists.txt finds Qt 6 components via find_package(Qt6 COMPONENTS Quick QuickControls2 Network REQUIRED).
• main.cpp creates a QQmlApplicationEngine, loads Main.qml, and
  returns from main().
• ApplicationController compiles as a QObject subclass with the
  Q_OBJECT macro.
• ApiTypes compiles and defines the structural shape of
  InvestmentCaseView fields (as C++ structs, not wire schema).
• CommandRegistry compiles as a stub with register() and dispatch()
  method signatures matching v3.19's five functions: CASE, POLICY, IMPACT,
  PROOF, SYSTEM.
• Main.qml displays the function mnemonics (CASE, POLICY, IMPACT, PROOF,
  SYSTEM) in a top bar using the Midnight Oni color scheme.
• Colors.qml defines the color palette from v3.19 as QML constants.
• The build is documented in justfile as build-tkni and follows the
  existing just recipe conventions (uses the os/arch variables from
  platform.sh where applicable).
• No build.zig changes are required for the Qt build.

Conditional Acceptance

Financial capability and policy

• N/A - story adds Qt build scaffolding; no policy changes.

Audit and replay

• N/A - story adds Qt build scaffolding; no audit/replay changes.

Runtime topology and tile ownership

• N/A - story adds Qt build scaffolding; no topology changes.

Model, tool, adapter, or execution boundary

• N/A - terminal does not call model/adapter/execution directly.

CaseOps API or UI

• N/A - QML shell is a presentation stub; real API client is V3.19.

Storage role: Memory, Analytics, Ledger

• N/A - story adds Qt build scaffolding; no storage changes.

Metrics, diagnostics, and operations

• N/A - story adds Qt build scaffolding; no metrics/telemetry changes.

Security and fail-closed behavior

• N/A - build POC only; no runtime security implications.

Evidence Plan

• Demo or command: just build-tkni on Linux x86, then run the compiled
  binary to verify it launches and renders the dark shell.
• Tests: Compilation success is the primary verification. Qt Quick tests are
  deferred to V3.19.
• Fixtures or samples: src/tickoni/terminal/ source tree.
• Audit/replay evidence: N/A - build POC.
• Blocked-flow evidence: N/A - build POC.

Quality Gate

• just build-tkni succeeds on Linux x86.
• The binary launches without crash or QML error.
• No build.zig changes introduced.
• Documentation and roadmap status are updated.

Notes And Open Questions

• Should Qt be built alongside the main Tickoni build (e.g., just build-all
  includes Qt) or as a separate just build-tkni? Story chooses separate —
  just build-all stays focused on Tickoni runtime.
• Should the CMakeLists.txt be under src/tickoni/terminal/ or at the repo
  root? Story chooses per-subproject CMake (src/tickoni/terminal/CMakeLists.txt)
  to keep the root build.zig untouched.
• Qt 6 version minimum: the story uses whatever is available on the dev
  environment; document the minimum version in the story or a brief note in
  doc/execution/build.md.