Here is the phased roadmap to achieve the project objectives while strictly adhering to the single-file and architectural constraints. 

### 1. Phase 1: Test Framework & Baseline Verification
*   **What will be done:** Create an end-to-end integration test suite using a script (e.g., `test.sh` or `test_runner.py`). This will include generating minimal valid (JPEG/PNG) and invalid test images. The script will execute the `ccolors` binary and assert against the terminal stdout and the generated `palette.json`.
*   **Why in this order:** Because the architecture forces a single-file design without separation of concerns, traditional unit testing is impossible. A black-box integration test suite must be established first to provide a safety net before any internal refactoring or optimizations occur.
*   **Definition of "Done":** The test script is fully executable (ideally integrated into `ctest` via CMake), runs automatically, and successfully validates the "happy path" (successful color extraction) and error paths (file not found, invalid format).
*   **Risk:** Extremely low risk as no production code is altered. **Rollback:** Delete the test script and revert `CMakeLists.txt`.

### 2. Phase 2: Core Debugging & Memory Optimization
*   **What will be done:** 
    1. **Debug:** Fix the file header check logic. Currently, `file.read(..., 8)` assumes the file is at least 8 bytes long. Furthermore, the file is read twice (once manually, once by `stbi_load`). This will be streamlined.
    2. **Optimize:** Eliminate the intermediate `std::vector<Pixel> samples` array. The brightness/saturation filtering and 16x16x16 histogram bucket accumulation will be calculated directly inside the `x` and `y` downsampling loops.
*   **Why in this order:** Fixing immediate crash risks on tiny/invalid files and removing unnecessary heap allocations (`std::vector` overhead) provides a robust, highly performant foundation before introducing new features.
*   **Definition of "Done":** The `vector<Pixel>` is entirely removed from the codebase, the program compiles without warnings, and the Phase 1 integration tests all pass.
*   **Risk:** The color quantization or sampling logic might inadvertently change, causing incorrect hex outputs. **Rollback:** `git checkout` the `main.cpp` file to its Phase 1 state.

### 3. Phase 3: Ease of Use Improvements
*   **What will be done:** Improve error messages and standard output control. Integrate `stbi_failure_reason()` to tell the user *why* an image failed to load (e.g., corrupted file vs. unsupported format). Add a `--quiet` (`-q`) CLI flag to suppress standard terminal output, making the tool friendly for automated scripts.
*   **Why in this order:** Usability features are best layered on top of a stable, optimized processing core. 
*   **Definition of "Done":** Running `ccolors corrupted.jpg` prints a highly specific error message. Running `ccolors image.jpg -q` generates the JSON file but prints absolutely nothing to standard output. 
*   **Risk:** Modifying the `argc/argv` parsing loop might accidentally break standard positional arguments. **Rollback:** Revert `main.cpp` to its Phase 2 state.

### 4. Phase 4: New Feature Integration
*   **What will be done:** Add an `--output` (`-o`) flag to allow users to specify a custom filename and path for the generated JSON file, replacing the hardcoded `palette.json` limitation. 
*   **Why in this order:** Adding new command-line routing introduces new code paths and file I/O operations. It relies on the extensible CLI parsing structure created in Phase 3.
*   **Definition of "Done":** Running `ccolors image.jpg -o /tmp/custom_colors.json` successfully parses the image and writes the JSON output specifically to the requested path. A corresponding test is added to the Phase 1 test suite and passes.
*   **Risk:** File stream failures (e.g., specifying a path in a non-existent directory or a read-only location) could crash the app if not handled gracefully. **Rollback:** Revert `main.cpp` to its Phase 3 state.

***

### Optional (Speculative / "Nice to Have")
*   **HTML Visualizer:** Add an `--html <file>` flag that outputs a standalone `.html` file with the extracted top 5 colors rendered as CSS colored blocks, providing a visual alternative to the terminal swatches.
*   **Multithreaded Downsampling:** Utilize C++17 `std::execution::par_unseq` or `#pragma omp parallel for` to parallelize the color extraction loops for massive performance gains on extremely high-resolution images.