AI Instructions for Decode-Orc

July 31, 2026 · View on GitHub

1. Overview & Core Constraints

1.1 Role & Scope

You are a coding assistant for the decode-orc project.
For pull-request workflows, see the separate PR templates in .github/PULL_REQUEST_TEMPLATE/.

Decode-Orc is a cross-platform orchestration framework for LaserDisc and tape decoding workflows. It provides both a GUI (orc-gui) and CLI (orc-cli) interface, sharing a common MVP-architected core (orc/core, orc/presenters, orc/view-types).

Type: C++ / Qt6 cross-platform application
Build system: CMake 3.20+ with vcpkg dependencies
Reproducible builds: Nix (recommended) with flake.nix
Target platforms: Linux (Flatpak), macOS (DMG), Windows (MSI)

1.2 Git Operations

Do not run git add, git commit, git push, git stash, or any command that modifies repository state unless the user explicitly requests it.
Read-only commands (git status, git log, git diff, git show) are permitted.

1.3 Naming

Never use planning-phase terminology (e.g., phase0, mvp-phase).
Use descriptive, domain-oriented names: signal_timing, sync_generator, burst_policy, frame_structure.

1.4 Content Restrictions

Do not include advertisements, promotions, or commercial references.
Omit "generated by", "co-authored by", or tool/service attributions.

2. Architecture & MVP Constraints

The project enforces MVP (Model-View-Presenter) pattern to keep layers decoupled. Do not bypass this:

Model/Core: orc/core/ — business logic, isolated from UI
Presenters: orc/presenters/ — translates core output to view models
View Types: orc/view-types/ — shared DTO-like structures
View: orc/gui/ and orc/cli/ — consume presenters, never touch core directly

Run ctest -R MVPArchitectureCheck to validate boundaries before submitting PRs.

MVP Enforcement Rules:

orc/core must never include GUI headers (Qt, presenters, or view-types)
orc/presenters must never include orc/gui or orc/cli headers
orc/gui and orc/cli must never directly access orc/core (use orc/presenters instead)
Cross-layer includes are detected by cmake/check_mvp_architecture.sh and enforced in CI/CD

Adding new features:

Business logic: Add implementation to orc/core/; add corresponding unit tests to orc-tests/core/unit/
Presentation layer: Add presenter in orc/presenters/ to translate core output; add view types to orc/view-types/ if needed
UI layer: Add GUI dialogs/widgets to orc/gui/ or CLI commands to orc/cli/; both consume presenters, never core directly

3. Security

Never hard-code secrets, tokens, credentials, or API keys in source, configs, or logs.
Use environment variables or a dedicated secrets manager for sensitive data.
Validate and sanitise all external inputs (file paths, CLI arguments, configuration).
Report suspected security issues privately (e.g., via security@project or GitHub Security Advisories).
Run git-secrets or equivalent scans before any commit you are asked to make.

4. Testing & Quality Assurance

4.1 General Rules

Source of truth: TESTING.md.
Unit tests are the primary methodology; prefer them for all new or modified behaviour.
Requirements:
- Mock dependencies; tests must be deterministic.
- No filesystem, network, system clock, database, or external service dependencies.
- Keep tests isolated and fast.
- Use interface-based dependency inversion and constructor injection.
- Name tests by behaviour (e.g., SyncGenerator_ProducesValidBurst_WhenGiven625LinePAL).
Classification:
- Every new or modified test must be marked in CMakeLists.txt as either unit or functional.
- Use functional only when the objective cannot be met with a unit test.
- Tests touching filesystem, real media, or full pipelines must be functional.
CI: the default unit-test lane must stay fast and mocked; do not add functional tests to it.

4.2 Unit Test Constraints (Non-Negotiable)

Unit tests MUST NOT access the filesystem, network, database, or system clock under ANY circumstances. This is enforced in code review:

❌ Forbidden: Creating temp files, reading JSON/YAML files, loading config files, accessing any external resource
❌ Forbidden: Directly calling code that touches disk/network (even "just to test happy path")
✅ Required: Mock ALL external dependencies via interfaces; inject mocks into the class under test
✅ Required: Test the class's logic in isolation; verify calls to dependencies, not the dependencies' behavior

Example: When testing metadata parsing logic that handles both "PAL_M" and "PAL-M" format names, do NOT read real JSON files. Instead, mock the metadata reader interface and feed it expected format-name strings directly through mocked method calls.

See TESTING.md "Unit tests" section and examples like daphne_vbi_writer_util_test.cpp for how to structure tests with proper mocking.

When adding/changing behavior:

Write or update unit tests first.
Mock external dependencies (file I/O, network, etc.).
Run the label-appropriate ctest invocation from TESTING.md locally.
Verify no new MVP violations: ctest -R MVPArchitectureCheck or cmake --build build --target check-mvp.

4.3 CTest Labels

Use CTest labels to keep local iteration and CI slices aligned with the repo conventions.

Label	Scope
`unit`	Fast GoogleTest-based unit-test suites
`mvp`	MVP architecture boundary check only (`MVPArchitectureCheck`)
`sdk`	SDK enforcement gates (PluginPrivateIncludeScan, PluginPrivateLinkScan)
`sources`	Source-stage unit tests
`transforms`	Transform-stage unit tests
`sinks`	Sink-stage unit tests
`contracts`	Cross-stage contract and registry coverage
`gui`	Any test in `orc-tests/gui/unit`
`gui-logic`	Tier 1 GUI helper tests with no `QApplication`
`gui-model`	Tier 2 GUI model/coordinator tests with `QCoreApplication`
`gui-widget`	Tier 3 offscreen widget/dialog tests

4.4 orc-core Expectations

For new stages and stage behavior changes, follow the orc-core section in TESTING.md.

Minimum definition of done for stage work:

Add the matching suite under orc-tests/core/unit/stages/<stage_id> in the same PR.
Register the suite with gtest_discover_tests(... PROPERTIES LABELS ...) using unit plus the appropriate family label.
Preserve shared contract coverage for registry, node discovery, parameter/default parity, and project-to-DAG wiring.
Update stage documentation (see §9.1): update instructions.md in the same PR whenever parameters, tools, or stage behaviour change.

4.5 orc-gui Expectations

For GUI testing tiers, offscreen harness details, and command examples, follow the orc-gui section in TESTING.md.

Required for GUI behavior changes in orc/gui/:

Enable BUILD_GUI_TESTS=ON.
Add tier-appropriate tests under orc-tests/gui/unit/ in the same PR.
Keep GUI tests at the presenter boundary; do not run a live orc-core pipeline in GUI unit tests.
Use QT_QPA_PLATFORM=offscreen for widget/dialog coverage.

Minimum GUI coverage expectations:

Pure helper logic: Tier 1 gui-logic coverage.
Model/coordinator classes: Tier 2 gui-model coverage with presenter-boundary mocks.
Dialog classes: Tier 3 gui-widget smoke coverage using the offscreen backend.
Parameter-editing dialogs: Tier 3 smoke coverage plus parameter round-trip coverage.
RenderCoordinator: request ordering, response delivery, stale-response suppression, and clean shutdown semantics.

4.6 Validation Gates

Run the narrowest set that matches the change scope before proposing changes.

Core-only or mixed changes:

cmake --build build -j
ctest --test-dir build --output-on-failure
ctest --test-dir build -R MVPArchitectureCheck --output-on-failure

GUI behavior changes:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_UNIT_TESTS=ON -DBUILD_GUI_TESTS=ON
cmake --build build -j
QT_QPA_PLATFORM=offscreen ctest --test-dir build -L gui --output-on-failure
ctest --test-dir build -R MVPArchitectureCheck --output-on-failure

5. C++ Coding Standards

5.1 Baseline & Tooling

Follow the Google C++ Style Guide.
Never use manual column-alignment (e.g. double-spacing before =, aligning continuation lines to opening parentheses) — clang-format will undo these and leave violations.
Use static analysers (clang-tidy) and sanitizers where available in the Nix environment.

5.2 Source File Headers

Every C++ source and header must start with an SPDX header above all other content.

Template:

/*
 * File:        signal_timing.cpp
 * Module:      timing
 * Purpose:     Generates PAL/NTSC horizontal sync and burst timing
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 * SPDX-FileCopyrightText: 2026 Contributor Name
 */

File must match the filename exactly (case-sensitive).
Module must describe the logical component.
Purpose must be a concise, domain-oriented description.

5.3 Custom Additions

5.3.1 Interface Design

Prefix abstract interface names with I (e.g., ILogger, IGenerationStage).
Methods: virtual with = 0 for pure virtual.
Always include a virtual destructor: virtual ~IInterfaceName() = default;

5.3.2 Memory Safety

Prefer RAII: use smart pointers (std::unique_ptr, std::shared_ptr) for ownership.
Use gsl::not_null<T*> or assertions for pointers that must never be null.
Range-check container access; prefer std::span or bounds-checked methods over raw arrays.
Document ownership semantics explicitly.

5.3.3 Concurrency

Document thread-safety guarantees for every public class or function.
Use std::mutex, std::atomic, or message-passing; never rely on undefined behaviour.
Mark shared vs thread-local state explicitly; prefer immutable data where possible.

5.3.4 File Organisation

Close namespaces with a trailing comment: } // namespace decode-orc

5.3.5 Constants & Clarity

Avoid magic numbers; define named constants with descriptive comments.
Reference authoritative specs when implementing standards (see §6.1).

5.3.6 Specification References

Format: // <Organization> <Document>-<Section>: <description>
Examples:
- // ITU-R BT.1700 Annex 1 Part B Table 1 item 1 (625-line PAL).
- // EBU Tech. 3280-E Section 1.2: 1135.0064 samples/line nominal
- // SMPTE 170M-2004 Section 11.3: 525 lines/frame, 2:1 interlace.
Supported organisations: EBU, ITU-R, ITU-T, SMPTE, IEC.

5.3.7 Commenting

Use inline comments above function declarations for purpose, parameters, and return values when non-obvious.
Explain the approach before complex algorithms.
Document rationale behind non-obvious decisions.
Use // TODO: <description>; avoid redundant comments.

6. Performance

Profile before optimising; prefer measurable gains over premature micro-optimisation.
Minimise copies: use references, move semantics, and const where possible.
Document Big-O complexity for public algorithms; note cache-locality assumptions where relevant.
Flag any change that increases memory use by >10 % or execution time by >5 % for design review.
For video-specific code, prefer SIMD-friendly memory layouts (e.g., planar YCbCr over interleaved RGB when the standard allows).

7. Development Environment & Build

The project uses Nix; the provided development shell is authoritative.
Run normal workflows inside the project shell: nix develop "path:$PWD" --command <command>
Temporary tools (profiling, debugging, one-off analysis):
- Use ad-hoc shells: nix shell nixpkgs#<tool> --command <tool> <args> nix shell nixpkgs#<tool1> nixpkgs#<tool2> --command <command>
Do not modify flake.nix or default.nix solely for temporary dependencies.
Always provide the Nix-based equivalent alongside plain shell commands.

Nix-based workflow (recommended):

flake.nix defines all external dependencies as flake inputs
- qtnodes (Qt node editor) is fetched from GitHub during nix develop / nix build
- ezpwd-reed-solomon headers are fetched from GitHub during nix develop / nix build
No git submodules required; Nix handles everything automatically
Simply run nix develop and dependencies are available
When already working inside nix develop, if a temporary extra tool is needed to complete the task, prefer nix shell to pull that tool into the active workflow instead of installing it through the host system or assuming it already exists

Non-Nix (CMake/vcpkg) workflow:

Dependencies are managed via vcpkg.json (manifest mode)
External dependencies may need manual setup (see BUILD.md for details)
Git submodules are NOT used in this project's primary workflow

Quick flow (Nix-based, recommended):

# Enter Nix development environment (all dependencies, reproducible)
nix develop

# Configure with tests enabled
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_UNIT_TESTS=ON

# Build
cmake --build build -j

# Run all tests + MVP architecture check
ctest --test-dir build --output-on-failure

Key build flags:

BUILD_GUI=ON (default) — build GUI; set OFF for CLI-only testing
BUILD_UNIT_TESTS=ON (local) / OFF (release) — controls unit test compilation
BUILD_GUI_TESTS=ON — enables the orc-tests/gui/unit test subtree when GUI behavior changes are in scope
CMAKE_BUILD_TYPE=Debug (local) / Release (packaging)
EZPWD_INCLUDE_DIR — path to ezpwd-reed-solomon headers (auto-set in Nix, required for manual builds)

For complete build instructions including Nix setup, CMake configuration, dependency management, and troubleshooting, see BUILD.md.

8. Project Structure

Repository root directory layout:

decode-orc/
├── orc/                           # Main project directory (CMake target root)
│   ├── common/                    # Shared utilities (logging, file I/O, exceptions)
│   ├── core/                      # Core business logic (MVP Model layer)
│   │   ├── stages/                # Processing pipeline stages
│   │   ├── metadata/              # Metadata handling
│   │   └── [business logic]
│   ├── view-types/                # Shared DTO structures (MVP shared layer)
│   │   └── [data transfer objects used by presenters & UI]
│   ├── presenters/                # Presenter layer (MVP Presenter)
│   │   └── [translates core output to view models]
│   ├── cli/                       # Command-line interface
│   │   └── main.cpp
│   └── gui/                       # Qt6 graphical interface (optional, BUILD_GUI=ON)
│       └── [Qt widgets & dialogs]
├── orc-tests/                     # Unified test tree (compiled when test flags are enabled)
│   ├── core/
│   │   └── unit/                  # Unit tests for core module
│   └── gui/
│       └── unit/                  # GUI unit tests
├── cmake/                         # CMake build utilities
│   ├── check_mvp_architecture.sh  # MVP boundary validation script
│   ├── MVPEnforcement.cmake       # MVP constraint macros
│   └── [other build helpers]
├── .github/                       # GitHub-specific configuration
│   ├── workflows/                 # CI/CD pipelines
│   └── ISSUE_TEMPLATE/
├── external/                      # Third-party dependencies
│   └── ld-decode-tools/           # Legacy ld-decode reference (checked in; available locally)
├── docs/                          # Documentation
├── assets/                        # Images, logos
├── CMakeLists.txt                 # Top-level CMake config
├── CMakePresets.json              # CMake build presets for all platforms
├── flake.nix                      # Nix reproducible build configuration
├── vcpkg.json                     # Dependency manifest (vcpkg)
├── BUILD.md                       # Build instructions (detailed)
├── TESTING.md                     # Testing strategy & patterns
├── CONTRIBUTING.md                # Contribution guidelines
└── README.md                      # Project overview

Module	Purpose	Dependencies	Can depend on
`orc/common`	Utilities (logging, file I/O)	None	—
`orc/core`	Business logic; no UI knowledge	common	common
`orc/view-types`	DTOs for presentation layer	—	common, core (read-only output types)
`orc/presenters`	Translates core → view models	core, view-types	common, core, view-types
`orc/gui`	Qt6 UI; consumes presenters	presenters, view-types, Qt6	presenters, view-types, common
`orc/cli`	CLI; consumes presenters	presenters, view-types	presenters, view-types, common
`orc-tests`	Unit tests (mocked dependencies)	gtest	any (for testing)

Key configuration files:

CMakeLists.txt (root): Top-level project setup, MVP enforcement, subdir inclusion (-DBUILD_UNIT_TESTS, -DBUILD_GUI)
orc/CMakeLists.txt: Main project config; defines build options; includes all subdirectories
CMakePresets.json: Build presets for all platforms (linux-gui-debug, macos-gui-debug, windows-gui-release, etc.)
flake.nix: Nix dev environment and reproducible build configuration
vcpkg.json: Dependency manifest (spdlog, Qt6, FFmpeg, sqlite, yaml-cpp, fftw, gtest)

Where to find things:

Tests: orc-tests/ (organized by source module, for example core/unit/ and gui/unit/)
Headers: orc/<module>/ (public headers in root; internal in subdirs)
Build outputs: build/bin/ (orc-gui, orc-cli); build/lib/ (libraries)
Generated files: build/generated/version.h (auto-generated version info)

9. SDK & Plugin Rules

All stage implementations (Decode-Orc supplied and third-party) must use only the public plugin SDK contract.

Do not include private host headers from orc/core, orc/gui, orc/cli, or orc/presenters in plugin-facing stage code.
Do not link plugin targets against private host internals outside approved SDK/plugin interfaces.
Do not add compatibility fallbacks or include-path workarounds that depend on in-tree private headers being present.
If an SDK capability is missing, expand the SDK first rather than bypassing it.

Plugin architecture and SDK documentation are published in docs/technical/plugin-architecture.md and docs/technical/plugin-sdk.md.

SDK documentation must be kept in sync with the implementation. When any of the following change, update the relevant doc file in the same PR:

Change	Doc to update
`kStagePluginHostAbiVersion` or `kStagePluginApiVersion` bumped	`orc/sdk/abi_history.yaml` (source of truth) → regenerate the `plugin-sdk.md` version-history block with `tools/gen_abi_history_docs.sh`; update the compatibility sections in both files. The `AbiHistorySync`/`AbiVersionDocsSync` gates and `tools/check_abi_bump.sh` enforce this
New or removed public SDK header (`orc/sdk/include/orc/abi/`, `orc/stage/`, or `orc/support/`)	`orc/sdk/sdk_headers.yaml` (single-source manifest) → regenerate the allowlist (`tools/gen_sdk_header_allowlist.sh` → `cmake/sdk_header_allowlist.txt`) and the `plugin-sdk.md` header tables (`tools/gen_sdk_header_docs.sh`). The `SdkHeaderManifestSync`/`SdkHeaderDocsSync` gates enforce this — do not hand-edit the allowlist or the generated tables
`StagePluginDescriptor`, entrypoint signatures, or callback contract changed	`plugin-architecture.md` — Compatibility Gating section
Registry YAML schema fields added or removed	`plugin-architecture.md` — Plugin Registry table
Curated plugin index (`registry_schema`) fields added or removed	`plugin-architecture.md` — Curated plugin index table; `orc-plugin-registry/README.md`
Artifact naming convention changed	Both files
`IStageServices` interface methods added or removed	`plugin-sdk.md` — Host services section
`StageToolDescriptor` / `AnalysisToolDescriptor` contract changed	`plugin-sdk.md` — Optional: Stage tools section
Plugin cache path or download behaviour changed	`plugin-architecture.md` — Plugin Registry section
Plugin or stage capability added or removed in `orc/gui` or `orc/cli`	`orc/plugin_ux_capabilities.yaml` (capability manifest; the `CLI.PluginUxCapabilityParity` gate enforces it) → `docs/cli-user-guide/overview.md` and `docs/gui-user-guide/dialogues/main.md`
`orc_add_stage_plugin()` macro signature changed	`plugin-sdk.md` — CMake Integration section

9.1 Stage Self-Documentation (Non-Negotiable)

Every stage plugin documents itself with a single artifact:

instructions.md — human-readable Markdown, located in the stage's plugin directory (e.g. orc/plugins/stages/<stage_id>/instructions.md). This is the single source of truth and is what the GUI help dialog renders. The stage class exposes it via the ORC_STAGE_INSTRUCTIONS_MD macro (in orc_stage_tooling.h), which reads the file from alongside the plugin shared library at runtime; orc_add_stage_plugin() copies the file next to the built plugin automatically.

Any PR that changes stage functionality, parameters, tools, or UX must update instructions.md in the same PR. Specifically:

Change	Required documentation update
Parameter added, removed, or renamed	`instructions.md` Parameters section
Parameter behaviour, range, or default changed	Same
Stage tool added, removed, or renamed	`instructions.md` Tools section
Stage tool behaviour or UX changed	Same
Stage's core behaviour or purpose changed	`instructions.md` What it does / When to use sections
New stage created	Create `instructions.md`; add `ORC_STAGE_INSTRUCTIONS_MD` to the class body

Third-party plugin authors should follow the same pattern. External plugins that cannot ship an instructions.md beside their shared library may instead embed the content inline via the legacy ORC_STAGE_INSTRUCTIONS(kInstructions_) macro; when both a file and inline content exist they must be kept identical.

9.2 SDK-Only Enforcement Gates (Active)

SDK-only compliance is enforced with hard-fail gates in CI/CD.

Do NOT attempt to work around these gates; they are non-negotiable:

Required Validation

Before opening a PR that adds or modifies stage plugins:

# Build with tests
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_UNIT_TESTS=ON
cmake --build build --parallel

# Run SDK enforcement gates (REQUIRED - must pass)
ctest --test-dir build -L sdk --output-on-failure

# Run runtime architecture validation
ctest --test-dir build -R "StagePluginLoader" --output-on-failure

If either hard gate fails (PluginPrivateIncludeScan or PluginPrivateLinkScan), the build is rejected. Fix all violations before submitting PR.

Gates in CI/CD

build-and-test.yml: Requires all -L sdk tests to pass before packaging workflows
All platforms: macOS, Windows, and Flatpak packaging workflows require build-and-test to succeed
Pre-commit locally: Run gates locally first to avoid failed CI runs

10. Documentation & Specifications

10.1 Authoritative Sources

CVBS file format:
- Start: docs-tech/cvbs-file-format-specification/README.md
- Full: docs-tech/cvbs-file-format-specification/docs/index.md
Analogue video standards (PAL, NTSC, SMPTE/ITU/EBU):
- Start: docs-tech/analogue-video-specifications/README.md
- Full: docs-tech/analogue-video-specifications/docs/index.md
Rule: if code conflicts with assumptions, align code and tests to the spec first.

10.2 Plugin SDK Documentation

Plugin architecture: docs/technical/plugin-architecture.md
Plugin SDK: docs/technical/plugin-sdk.md

11. CI/CD & Multi-Platform

Current workflows (.github/workflows/):

build-and-test.yml: Runs on Linux with Nix; executes CMake config, build, and ctest.
package-macos.yml: Builds on macOS; uses Homebrew + manual vcpkg. DMG output.
package-flatpak.yml: Builds on Linux; produces Flatpak bundle.
package-windows.yml: Builds on Windows with MSVC 2022 & vcpkg; produces MSI.
release-from-artifact.yml: Publishes artifacts to GitHub Releases (tags only).

Before proposing changes:

Test locally with the Nix/Linux flow (primary CI gate).
If modifying build system, packaging, or dependencies, review the platform-specific workflow file for that target.
Document in PR what was validated locally and what could not be (e.g., "Unable to validate Windows MSI build on Linux"; add flag for reviewers to test).

12. Licensing & Legal Requirements

Decode-Orc is licensed under GPLv3. All dependencies and contributions must be compatible with GPLv3:

Permitted licenses: GPLv3, GPLv2, LGPL, BSD, MIT, Apache 2.0, ISC, and similar permissive licenses
Incompatible licenses: AGPL (stronger copyleft), proprietary/closed-source, SSPL
Check before adding: Always verify a new dependency's license in its repository or LICENSE file before proposing a PR

For contributors:

When adding a new dependency (via vcpkg.json or flake.nix), document its license
If you're unsure about license compatibility, ask in the issue or PR
vcpkg.json and flake.nix changes will be reviewed for license compliance during CI/CD

License file location: See LICENSE in the repository root (GPLv3).

13. Contribution Hygiene

Focused changes: One clear problem per PR.
Commit messages: Clear, descriptive; reference issue numbers.
Documentation: Update README.md and docs if behavior or usage changes (see BUILD.md for build-related changes).
Avoid refactoring unrelated code — saves iteration and speeds review.
Search existing issues and PRs first to avoid duplicates.

14. Implementation Planning

Structure plan documents as phased tasks for agentic coding.
Requirements:
- ≤ 10 tasks per phase (ideally 3–5).
- Clear descriptions and acceptance criteria per task.
- No decorative sections (TOC, summaries).
- No timelines or resource estimates.
- Each phase must be self-contained and actionable.
- Link directly to referenced specs, designs, or sources.
- Follow testing rules from TESTING.md and §4.
Change history belongs in git; do not include it in plan files.

15. Guardrails

Trust the instructions: Use them as the source of truth. Search codebase only if instructions are incomplete or found to be incorrect.
Verify build commands: If docs disagree with working workflows, workflows are correct; flag the discrepancy in your PR.
Respect architecture: MVP layer boundaries are enforced by tests and CI.
Test first, refactor never: Don't introduce new frameworks or patterns unless explicitly requested; follow existing conventions.

16. Communication Style

Be concise; prefer bullet lists and fenced code blocks over prose.
Explain non-obvious choices or trade-offs in one short sentence.
Cite authoritative specs, files, or line numbers when referencing requirements.
Use markdown headers and separators to structure long responses.

17. Clarification Triggers

Ask the user when:

Requirements are ambiguous or contradictory.
A change affects public APIs, file formats, or backwards compatibility.
Multiple valid approaches exist with significantly different trade-offs.
A task may have security, licensing, or performance implications.

18. Common Commands Reference

# Clean build
rm -rf build && cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_UNIT_TESTS=ON -DBUILD_GUI_TESTS=ON && cmake --build build -j

# Run only unit tests (skip MVP check)
ctest --test-dir build -E MVPArchitectureCheck --output-on-failure

# Check MVP architecture only
ctest --test-dir build -R MVPArchitectureCheck

# Run all GUI tests with the offscreen backend
QT_QPA_PLATFORM=offscreen ctest --test-dir build -L gui --output-on-failure

# Run a GUI widget slice only
QT_QPA_PLATFORM=offscreen ctest --test-dir build -L gui-widget --output-on-failure

# Build without tests (faster for iteration)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_UNIT_TESTS=OFF && cmake --build build -j

# Run a specific test
ctest --test-dir build -R "test_name_pattern" --output-on-failure