Resolve pending commit links of the MIL-013 results

MIL-013: results of the container and sandbox checks
Review record RC-079 (Go-with-conditions): the Debian checks and the Linux smoke tests pass; the Windows Sandbox run is pending because it opens a window on the host. Task: MIL-013#8
2026-10-15 10:10:11 +08:00 · 2026-10-15 10:10:10 +08:00 · 2026-10-15 10:09:48 +08:00 · 2026-10-15 03:55:36 +02:00 · 2026-10-15 09:55:23 +08:00 · 2026-10-15 09:55:21 +08:00
40 changed files with 1877 additions and 32 deletions
@@ -0,0 +1,15 @@
 .git
 .venv
 .env
 .env.*
 .codex
 **/__pycache__
 **/*.pyc
 .pytest_cache
 .mypy_cache
 .ruff_cache
 .import_linter_cache
 build
 dist
 docs/doxygen
 data/words_to_learn*.csv
@@ -3,3 +3,7 @@
 *.toml text eol=lf
 *.csv text eol=lf
 *.png binary
 *.sh text eol=lf
 *.Dockerfile text eol=lf
 .dockerignore text eol=lf
 *.ps1 text eol=crlf
@@ -4,6 +4,35 @@ All notable changes of the flash card program. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the version follows
 [Semantic Versioning](https://semver.org/).
 ## [0.2.0] - 2026-10-15
 Adds the classic menu bar and keeps the progress of each word list apart.
 ### Added
 - A menu bar. File: Open... (another word list from a CSV file with a header
  of two language codes), Change level... (the level choice without a restart),
  Reset word list... (after a confirmation the progress of the open list is
  removed and all its words are to learn again), Exit. About: Contact (the
  author's name and title, and a link to the author's LinkedIn page).
 - The progress of each word list is a file of its own: `words_to_learn.csv` for
  `ms-da.csv` (unchanged) and `words_to_learn_<name>.csv` for another list.
 ### Fixed
 - A word list that is not UTF-8 text gives a message that names the file,
  instead of an error.
 - The level screen has the same window title, padding and background as the
  card screen.
 ### Known limits
 - The executable is not signed; Windows SmartScreen may warn about it.
 - The executable is not attached to the release: the upload limit of the git
  host rejects a file of its size (HTTP 413, already at 1 MB). Build it with
  `python tools/build_executable.py`.
 - An opened word list is not remembered after a restart.
 ## [0.1.0] - 2026-10-15
 First release. The solution of day 31 of Udemy's *100 Days of Code: The Complete
@@ -32,3 +61,4 @@ Python Pro Bootcamp*, for Malay words with Danish translations.
 - The Danish column of the word list is machine translated.
 [0.1.0]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.1.0
 [0.2.0]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.2.0
@@ -4,7 +4,7 @@
 PROJECT_NAME           = "Flash Card"
 PROJECT_BRIEF          = "Malay to Danish flash cards (Udemy 100 Days of Code, day 31)"
-PROJECT_NUMBER         = 0.1.0
+PROJECT_NUMBER         = 0.2.0
 OUTPUT_DIRECTORY       = docs/doxygen
 CREATE_SUBDIRS         = NO
@@ -120,7 +120,7 @@ The progress of the delivered `ms-da.csv` is `data/words_to_learn.csv`; another
 ### Executable (Windows, no Python needed to run it)
-The [release page][release-0-1-0] of v0.1.0 has the release notes. The executable is not attached there yet, because the server's upload limit rejects a file of this size (HTTP 413). Build it yourself:
+The release pages of [v0.2.0][release-0-2-0] and [v0.1.0][release-0-1-0] have the release notes. The executable is not attached there yet, because the server's upload limit rejects a file of this size (HTTP 413). Build it yourself:
 ```powershell
 python -m pip install -e ".[build,speech]"
@@ -147,6 +147,26 @@ The window test in `tests/e2e/` is skipped when no display is available.
 Build the source code documentation (Doxygen comments) with `doxygen Doxyfile`; the HTML is written to `docs/doxygen/html/`. The screenshots are made with `python tools/capture_screenshots.py` after `python -m pip install -e ".[tools]"` (Pillow, tool only).
 ### Checks without a desktop (Docker)
 The tests, the linters, the screenshots and a smoke test of a Linux binary run in a Debian container on a virtual screen, so no window opens on your own desktop.
 ```bash
 docker build -f docker/debian.Dockerfile -t flash-card-debian .
 # linters and the whole test suite, including the real window tests
 docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh run-checks.sh
 # screenshots into ./build/container-out
 docker run --rm -v "$PWD:/repo:ro" -v "$PWD/build/container-out:/out" flash-card-debian bash /repo/tools/docker/in-container.sh screenshots.sh /out
 # build the Linux binary and press the known button 5 times (binary and source)
 docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh smoke-binary.sh 5
 ```
 On Windows PowerShell write `${PWD}` for `$PWD`. The repository is mounted read-only and copied inside the container.
 - The desktop is Xvfb with GNOME's window manager (mutter). GNOME Shell is tried first and does not start in a container (it needs a login manager), so the scripts fall back to mutter and print which one ran.
 - The Windows executable is checked in **Windows Sandbox** (Windows 11 Pro, feature enabled): `powershell -File tools\sandbox\run.ps1 -Runs 5` after `python tools/build_executable.py`. The sandbox shows its own window while it runs; the click is made inside the sandbox.
 - Not covered: macOS (it cannot be run in Docker on Windows or Linux and Apple's licence allows it only on Apple hardware), and Windows itself in the Debian container.
 ## 📄 License
 GNU Affero General Public License v3.0 or later. See [LICENSE][license].
@@ -156,7 +176,7 @@ GNU Affero General Public License v3.0 or later. See [LICENSE][license].
 - [Repository][repository]
 - [Documentation][documentation]
 - [Issue tracker][issues]
- [Releases][releases] (v0.1.0: release notes; the executable is built from source, see Run)
+- [Releases][releases] (v0.2.0 and v0.1.0: release notes; the executable is built from source, see Run)
 ## 📎 Appendix: Project documents
@@ -191,6 +211,7 @@ The documents a newcomer needs, in reading order.
 [issues]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/issues
 [releases]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases
 [release-0-1-0]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.1.0
 [release-0-2-0]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.2.0
 [agents]: ./AGENTS.md
 [BC-001]: ./docs/business-case.md
 [SA-001]: ./docs/stakeholder-analysis.md
@@ -0,0 +1,45 @@
 # Debian based image for the flash card checks (ADR-0005).
 #
 # Build (from the repository root):
 #   docker build -f docker/debian.Dockerfile -t flash-card-debian .
 # Run the linters and the tests on a virtual desktop:
 #   docker run --rm -v "$PWD:/app" flash-card-debian
 #
 # The base image is the official Python image (Debian bookworm), because the
 # program needs Python 3.13. The desktop is a virtual X screen (Xvfb) with
 # GNOME Shell when it can start in a container, else GNOME's window manager.
 FROM python:3.13-slim-bookworm
 ENV DEBIAN_FRONTEND=noninteractive \
    PYTHONUNBUFFERED=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1 \
    DISPLAY=:99
 RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      xvfb xauth x11-utils x11-xserver-utils xdotool dbus dbus-x11 \
      procps ca-certificates \
      libgl1-mesa-dri libegl1 libgles2 \
      mutter gnome-session gnome-shell gnome-settings-daemon \
      adwaita-icon-theme gsettings-desktop-schemas \
      tk fonts-liberation fonts-dejavu-core \
 && rm -rf /var/lib/apt/lists/*
 # PyInstaller on Linux needs objdump (binutils).
 RUN apt-get update \
 && apt-get install -y --no-install-recommends binutils \
 && rm -rf /var/lib/apt/lists/*
 RUN useradd --create-home --shell /bin/bash flash
 WORKDIR /app
 # Dependencies first, so a change of the sources does not rebuild this layer.
 COPY pyproject.toml README.md LICENSE ./
 COPY src ./src
 RUN python -m pip install --upgrade pip \
 && python -m pip install -e ".[dev,speech,tools,build]" \
 && chown -R flash:flash /app
 USER flash
 ENV PATH="/app/tools/docker:${PATH}"
 CMD ["bash", "tools/docker/run-checks.sh"]
@@ -0,0 +1,55 @@
 # ADR-0005: Container and sandbox checks without the user's desktop
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | ADR-0005 |
 | CrossReference | [BC-001], [ADR-0004] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f86bc91] |
 Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
 ---
 ## Context
 Smoke tests of the program drive a real window. Run on the Product Owner's own Windows desktop they open windows, take the focus and move the mouse, which interrupts the Product Owner's work (RC-072). The checks must run somewhere else. Options:
 1. A Windows hidden desktop (a second Win32 desktop of the same session): invisible, but still the host's session and a place where a mistake can reach the host.
 2. A Debian Docker container with a virtual X screen and GNOME for the Linux checks, and Windows Sandbox for the Windows executable: both are isolated from the host's input and desktop; the Debian check is not a Windows check.
 3. A Wine container for the Windows executable, or a real Windows virtual machine run in Docker with KVM: Wine is an emulation of the Windows interface; the Windows virtual machine needs a Microsoft evaluation image of tens of gigabytes and licence terms the Product Owner has not accepted.
 4. macOS in Docker: not possible on a Windows host, and Apple's licence allows macOS only on Apple hardware.
 ## Decision
 Run the Linux checks (linters, tests including the real window, screenshots, a Linux binary and its smoke test) in a Debian image based on `python:3.13-slim-bookworm` with Xvfb, GNOME's window manager and, if it runs in a container, the GNOME session. Run the Windows executable in Windows Sandbox of Windows 11 Pro through a `.wsb` configuration and a script that presses the known button inside the sandbox and writes the result to a mapped folder. Do not run macOS, and state that in the documents.
 ## Consequences
 **Positive:**
 - No check takes the focus or the mouse of the host any more.
 - The container checks are repeatable on any machine with Docker and need no Python installation.
 - The sandbox is a real Windows, thrown away after each run.
 **Negative:**
 - The Debian image is large (a desktop and a Python image) and the first build takes time.
 - A full GNOME session may not run in a container; the fallback (GNOME's window manager) is a weaker statement, and the record says which one ran.
 - Windows Sandbox needs Windows 11 Pro with the feature enabled and shows its own window on the host while it runs.
 - macOS stays untested.
 ## Affected Artifacts
 - [BC-001] — In Scope and Out of Scope lists
 - [ADR-0004] — the executable that the sandbox runs
 ---
 [BC-001]: ../business-case.md
 [ADR-0004]: ./adr-0004-pyinstaller-executable.md
 [f86bc91]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f86bc9136e7719fbcd049a4f803959019b7d2df3
@@ -14,7 +14,7 @@ document of a type. `Primary File` may contain a glob (e.g.
 | BC | Business Case | docs/business-case.md | 002 |
 | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
 | PP | Project Plan | docs/project-plan.md | 002 |
-| MIL | Milestone / Gateway | docs/milestones/*.md | 013 |
+| MIL | Milestone / Gateway | docs/milestones/*.md | 014 |
 | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
 | US | User Story | docs/user-stories.md | 002 |
 | UC | Use Case | docs/uc-*/uc.md | 002 |
@@ -24,8 +24,8 @@ document of a type. `Primary File` may contain a glob (e.g.
 | SSD | System Sequence Diagram | docs/uc-*/ssd.md | 002 |
 | DCD | Design Class Diagram | docs/dcd.md | 002 |
 | DICT | Domain Dictionary | docs/dictionary.md | 002 |
-| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0005 |
+| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0006 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 071 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 080 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
 ## Languages
@@ -11,8 +11,8 @@
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-15 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | In Scope: menu bar (new request of S01) | [2211d0f] |
+| 2026-10-15 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Scope: tagged releases v0.1.0 and v0.2.0 (new request of S01) | [0264b60] |
-| 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Scope: tagged releases v0.1.0 and v0.2.0 (new request of S01) | [0264b60] |
+| 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Scope: container and sandbox checks (new request of S01) | [f86bc91] |
 ---
@@ -55,6 +55,7 @@ A small, well-structured reference solution gives the Product Owner a language l
 - Optional spoken Malay word (text to speech) as an extra that can be installed.
 - A choice of level (the first 100 words, the first 1000 words or all words of the frequency ordered word list) before learning starts.
 - A menu bar with the commands to open another word list (CSV), change the level, reset a word list, exit, and the author's contact.
 - Checks that do not use the user's desktop: a Debian based Docker image with a virtual GNOME desktop for the tests, headless screenshots and a Linux binary, and Windows Sandbox for the Windows executable.
 - A single Windows executable file, built with PyInstaller by a script of this repository, that runs without an installed Python.
 - Tagged releases of the repository (`v0.1.0`, `v0.2.0`), each with release notes and, when the git host accepts the upload, the executable and its SHA-256 checksum attached.
 - `pyproject.toml`, `.gitignore`, `Doxyfile`, virtual environment instructions, `pytest` tests and `constants.py`.
@@ -66,6 +67,7 @@ A small, well-structured reference solution gives the Product Owner a language l
 - Other languages: the user interface labels are Malay and Danish only; another word list works by changing the data file but is not delivered.
 - Spaced repetition scheduling, statistics, accounts, cloud synchronisation and mobile apps.
 - Running macOS or a Windows virtual machine other than Windows Sandbox in the checks (macOS is not run in Docker: Apple's licence allows it only on Apple hardware).
 - Packaging for distribution on PyPI, an installer and a signed executable (the executable built with PyInstaller and its release on the git host are in scope; the file itself is not committed to the repository).
 - Redistribution of the course's own image files; the card and button images are generated for this project.
 - A translation quality review of the word list.
@@ -151,5 +153,5 @@ Proceed — the scope is small, the risks are mitigated, and the result serves t
 ---
 [SA-001]: ./stakeholder-analysis.md
 [2211d0f]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/2211d0f4cbd8182314d18cbdefd939ae50c39e6d
 [0264b60]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/0264b6084f26bac5af716ea71596ce3be961fec8
 [f86bc91]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f86bc9136e7719fbcd049a4f803959019b7d2df3
@@ -0,0 +1,88 @@
 # MIL-013: Container checks
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | MIL-013 |
 | CrossReference | [BC-001], [DCD-001], [ADR-0004] |
 | Language | en |
 | Domain | it |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f86bc91] |
 ---
 ## Purpose
 Decide whether the program can be built, tested and run without touching the Product Owner's own desktop: a Docker container gives a Debian desktop (GNOME) on a virtual screen, and Windows Sandbox (a disposable Windows virtual machine of Windows 11 Pro) runs the Windows executable on a desktop of its own. The checks that earlier took over the Windows desktop (mouse clicks, windows opening) move into the containers.
 ## Deliverable
 - A Debian image (`python:3.13-slim-bookworm`) with GNOME's window manager and session, a virtual X screen, Tk and fonts, that runs the linters and the whole test suite (including the e2e tests of the real window), the headless run with screenshots, and a PyInstaller build of a Linux binary with its smoke test.
 - A Windows Sandbox check of the Windows executable: a `.wsb` configuration and a PowerShell script (`tools/sandbox/`) that start a disposable Windows 11 virtual machine with the built `dist/` mapped read-only and an output folder mapped read-write, start the executable on the sandbox's own desktop, press the known button inside the sandbox, check the progress file, take screenshots, write the results to the output folder and shut the sandbox down. The mouse and the keyboard used are those of the sandbox, not of the host.
 - macOS is not covered, and the documents say why (see ADR-0005).
 ## Go / No-Go Criteria
 | # | Criterion (objectively checkable) | Go | No-Go |
 | --- | --- | --- | --- |
 | 1 | `docker build` of the Debian image succeeds on the Product Owner's Docker Desktop (Linux containers) | Exit code 0 | A build error |
 | 2 | In the Debian image the linters and the whole test suite run on the virtual screen with the GNOME window manager and end with exit code 0, with the e2e tests counted as passed (not skipped) | Output and exit code | A skipped or failing test |
 | 3 | The full GNOME session (`gnome-session` with its shell) is tried in the container; the result is recorded; when it cannot run in a container the checks use GNOME's window manager (mutter) and the record says so | Result in the review record | An unstated fallback |
 | 4 | During the container runs nothing opens or moves on the host desktop; during a sandbox run the only host effect is the sandbox's own window, and the sandbox is closed by its script | Nothing else seen on the host | A host window other than the sandbox or any host click |
 | 5 | The screenshot script writes the level screen, the card front, the card back and the window with the menu bar as PNG files to a mounted folder, from the Debian image | Four readable PNG files | A missing or blank file |
 | 6 | A Linux binary is built in the container and its smoke test passes: the window appears, the level screen is shown, a known word is pressed through the virtual input of the screen and the progress file has one card less, the list override is used | Script output and exit code 0 for 5 consecutive runs | A failing run |
 | 7 | The Windows executable passes the same smoke test inside Windows Sandbox (window titled Flashy, embedded list, list override, known button writes the progress file), 5 consecutive sandbox runs, with the results read from the mapped output folder | Result files of 5 runs | A failing run, or a run that needs the host mouse |
 | 8 | The lost-click symptom of RC-072 is investigated with the container test (a repeated press of the known button on the same executable) and the finding is recorded: program defect or test harness | Finding in the review record | No finding |
 | 9 | README and the wiki Install page in three languages describe the commands and state that macOS is not covered, that the sandbox needs Windows 11 Pro with Windows Sandbox enabled, and that the Debian check is not a Windows check; `check-readme.sh` exit 0 | Exit code 0 | A missing statement |
 | 10 | BC-001 and PP-001 are updated and ADR-0005 records the decision and its limits (including why macOS is not run in Docker); each reviewed `Go`; code review against QC-PY-001 has no failed Mandatory criterion; the linters are clean | `RC-*` verdict Go | Otherwise |
 ## ## Dependencies
 | Depends on | Reason |
 | --- | --- |
 | MIL-012 | The version 0.2.0 of the program, the built executable and the open condition (RC-072) about its smoke test |
 ## Traceability
 | Business Case objective / KPI / user story | Reference |
 | --- | --- |
 | Objective 4 (a repository others can use) and success criterion 2 (tests run on a clean environment) | [BC-001] |
 | The condition of RC-072 on the executable smoke test (Linux part) | [MIL-012] |
 ## Ownership
 | Role | Stakeholder ID (SA) |
 | --- | --- |
 | Owner | S01 |
 | Approving reviewer | S01 (AI as stand-in in autonomous mode) |
 ## Target Date
 2026-10-19 — within the delivery window that ends 2026-10-21 ([BC-001] constraint).
 ## Tasks
 | # | Task | Summary | Needs its own Use Case/User Story? | Reference |
 | --- | --- | --- | --- | --- |
 | 1 | Update the documents for the container checks | BC-001 (In Scope: Docker images for tests and headless runs; Out of Scope: macOS, a signed or installed Windows setup), PP-001 and a new ADR-0005 (the Debian image with GNOME, Windows Sandbox for the Windows executable, what is covered and why macOS is not run in Docker: Apple's licence allows macOS only on Apple hardware); each changed document gets a Version History row and a review. | No | BC-001, ADR-0004 |
 | 2 | Add the Debian image with GNOME | `docker/debian.Dockerfile` and `.dockerignore`: `python:3.13-slim-bookworm`, `xvfb`, `xauth`, `dbus-x11`, `mutter`, `gnome-session` and `gnome-shell`, `tk`, `fonts-liberation`, `x11-utils`, `xdotool`, a non-root user; the project installed with `[dev,speech,tools,build]`. | No | ADR-0005 |
 | 3 | Start a GNOME session on the virtual screen | `tools/docker/start-desktop.sh` starts `dbus`, Xvfb and `gnome-session` (or, if the session cannot run in a container, mutter alone) and waits until the desktop is up; the choice is printed and recorded. | No | |
 | 4 | Add the check scripts | `tools/docker/run-checks.sh`, `screenshots.sh` and `smoke-binary.sh`; each one purpose, `set -euo pipefail`, shellcheck clean, all run under the desktop of task 3. | No | |
 | 5 | Make the screenshot tool work on Linux | `tools/capture_screenshots.py` chooses the platform: Windows as now, Linux grabs the X screen with Pillow and crops to the window; the pure parts are unit tested. | No | |
 | 6 | Add the headless smoke driver | A script that starts the program or the binary, finds the window with `xdotool`, presses the known button with the virtual input of the screen, and checks the progress file, with a repeat count so the lost-click symptom of RC-072 can be measured; the sandbox script does the same with the sandbox's input. | No | |
 | 7 | Add the Windows Sandbox check | `tools/sandbox/flash-card.wsb` (mapped folders: `dist` read-only, `out` read-write; logon command), `tools/sandbox/smoke.ps1` (runs inside the sandbox: copy the executable, start it, wait for the window, press the known button with the sandbox's own input, read the progress file, take screenshots, write a result file and shut the sandbox down) and `tools/sandbox/run.ps1` on the host (starts the sandbox with the generated configuration and waits for the result file). | No | ADR-0005 |
 | 8 | Run and record the checks | Build the image, run the scripts and the smoke tests 5 times each in the container and 5 times in the sandbox, record counts, sizes, durations and the GNOME session result; record the finding on the lost click. | No | |
 | 9 | Test the pure parts | Unit tests for the platform choice and the box calculation of the capture tool and for the argument handling of the smoke driver. | No | |
 | 10 | Update README and wiki | README and the Install page of the wiki in English, Danish and Bahasa Malaysia: the commands, the output folders, the limits (the Debian check is not a Windows check, the sandbox needs Windows 11 Pro, macOS is not covered); the wiki is republished after the merge. | No | |
 ---
 [BC-001]: ../business-case.md
 [DCD-001]: ../dcd.md
 [ADR-0004]: ../adr/adr-0004-pyinstaller-executable.md
 [MIL-012]: ./mil-012-release-0-2-0.md
 [f86bc91]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f86bc9136e7719fbcd049a4f803959019b7d2df3
@@ -4,15 +4,15 @@
 | Key | Value |
 | --- | --- |
 | ID | PP-001 |
-| CrossReference | [BC-001], [SA-001], [US-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011], [MIL-012] |
+| CrossReference | [BC-001], [SA-001], [US-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011], [MIL-012], [MIL-013] |
 | Language | en |
 | Domain | it |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-15 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added gateway MIL-011 Menu bar (new request of S01) | [2211d0f] |
+| 2026-10-15 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added gateway MIL-012 Release v0.2.0 (new request of S01) | [0264b60] |
-| 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added gateway MIL-012 Release v0.2.0 (new request of S01) | [0264b60] |
+| 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added gateway MIL-013 Container checks (new request of S01) | [f86bc91] |
 ---
@@ -44,6 +44,7 @@ This plan schedules the seven phases (gateways) that deliver the flash card prog
 | Release v0.1.0 | [MIL-010] | 2026-10-16 | 2026-10-16 | S01 | US-001.08 | Tag v0.1.0 and a release with `flash-card.exe`, its checksum and release notes | |
 | Menu bar | [MIL-011] | 2026-10-17 | 2026-10-17 | S01 | US-001.09 to US-001.12 | File menu (open word list, change level, reset word list, exit) and About menu (contact); documents, wiki and screenshots updated | |
 | Release v0.2.0 | [MIL-012] | 2026-10-18 | 2026-10-18 | S01 | US-001.08 | Version 0.2.0, tag `v0.2.0` and a release with the menu bar, notes and, if the host accepts it, the executable | |
 | Container checks | [MIL-013] | 2026-10-19 | 2026-10-19 | S01 | none | A Debian (GNOME) container and Windows Sandbox that run the tests, screenshots and the smoke tests without the host desktop | |
 ```plantuml
@startgantt
@@ -72,6 +73,8 @@ Project starts 2026-10-14
 [Menu bar Go/No-Go] happens 2026-10-17
 [Release 0.2.0] starts 2026-10-18 and ends 2026-10-18
 [Release 0.2.0 Go/No-Go] happens 2026-10-18
 [Container checks] starts 2026-10-19 and ends 2026-10-19
 [Container checks Go/No-Go] happens 2026-10-19
@endgantt
 ```
@@ -91,12 +94,13 @@ Project starts 2026-10-14
 | Release with the executable attached (new request after MIL-009) | MIL-010 |
 | Menu bar with File and About menus (new request after MIL-009) | MIL-011 |
 | Release v0.2.0 with the menu bar (new request after MIL-011) | MIL-012 |
 | Debian container for tests and headless runs (new request after MIL-012) | MIL-013 |
 | Framework documents of the baseline | Baseline pull request before MIL-001 |
 ## Dependencies
 ```
-Baseline → MIL-001 → MIL-002 → MIL-003 → MIL-004 → MIL-005 → MIL-006 → MIL-007 → MIL-008 → MIL-009 → MIL-010 → MIL-011 → MIL-012
+Baseline → MIL-001 → MIL-002 → MIL-003 → MIL-004 → MIL-005 → MIL-006 → MIL-007 → MIL-008 → MIL-009 → MIL-010 → MIL-011 → MIL-012 → MIL-013
 ```
 A No-Go on a phase moves every later date by the days the rework takes; MIL-008 was added after MIL-007 and takes the unplanned day 2026-10-20, so no buffer is left inside the window; a No-Go moves the end date past 2026-10-21 and S01 decides whether to accept that.
@@ -131,6 +135,7 @@ A No-Go on a phase moves every later date by the days the rework takes; MIL-008
 [MIL-010]: ./milestones/mil-010-release.md
 [MIL-011]: ./milestones/mil-011-menu-bar.md
 [MIL-012]: ./milestones/mil-012-release-0-2-0.md
 [MIL-013]: ./milestones/mil-013-container-checks.md
 [MS-001]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/milestone/165
 [MS-002]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/milestone/166
 [MS-003]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/milestone/167
@@ -138,5 +143,5 @@ A No-Go on a phase moves every later date by the days the rework takes; MIL-008
 [MS-005]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/milestone/169
 [MS-006]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/milestone/170
 [MS-007]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/milestone/171
 [2211d0f]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/2211d0f4cbd8182314d18cbdefd939ae50c39e6d
 [0264b60]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/0264b6084f26bac5af716ea71596ce3be961fec8
 [f86bc91]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f86bc9136e7719fbcd049a4f803959019b7d2df3
@@ -0,0 +1,64 @@
 # RC-071: Review of PY-MIL-012
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-071 |
 | CrossReference | [PY-MIL-012], [QC-PY-001] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [7c1f1b6] |
 ---
 ## Artifact Under Review
 - Instance reviewed: [PY-MIL-012]
 - Checklist used: [QC-PY-001]
 - Scope: full review
 - Language and domain: n/a (technical type)
 - Language reviewer: none
 - Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | The change is one assignment and a test module; names follow PEP 8. |
 | 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | `test_version_of_the_package_equals_pyproject_version` and similar names state the behaviour. |
 | 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff check` and `ruff format --check` pass with no suppressions. |
 | 4 | Every function and method signature is type-annotated, including `-> None` | Pass | Test functions are annotated `-> None`; `mypy --strict` passes on 49 source files. |
 | 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | No exception handling in the change. |
 | 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults. |
 | 7 | Files, locks and connections are managed with context managers | Pass | `pyproject.toml` is read with `tomllib` through a `with open` context. |
 | 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | The module docstring keeps `@file` and `@brief`; `doxygen Doxyfile` ends with 0 warnings. |
 | 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | Pass | No `print`, no logging in the change. |
 | 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | Pass | No class or operation changed; the version string is not part of the design. |
 | 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | 3 tests compare `__version__`, `pyproject.toml` and the `Doxyfile` `PROJECT_NUMBER` and the `MAJOR.MINOR.PATCH` form; 3 consecutive full runs (261 tests) green. |
 | 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | `mypy --strict` reports no issue. |
 | 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | `dependencies` stays empty; `tomllib` is standard library. |
 | 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | The version is stated once per file type; the test makes the three places agree. |
 | 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | `lint-imports` reports `Layers point inward` kept. |
 | 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | One test module with one reason to change. |
 | 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | The test sits in `tests/unit`. |
 | 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | File names follow the rule. |
 ## Overall Verdict
 Go — every Mandatory criterion passes. Reviewed by AI as stand-in for S01; not independent of the author.
 Milestone MIL-012 tasks 2, 3, 4 and 8 (this change set): 1 the three version places say 0.2.0 and a test fails if they differ; 2 CHANGELOG has `[0.2.0]` and `[0.1.0]` is unchanged; 3 the upload limit probe ran before the build: a draft release with a 1 MB random file was refused with `413 Request Entity Too Large`, so the largest accepted size is below 1 MB; the draft release and its tag were deleted afterwards (the tag list and the release list were checked); 8 README, CHANGELOG and the Install page of the wiki in three languages link v0.2.0 and say that the executable is not attached; `check-readme.sh` exit 0. The tag, the build and the release are criteria 4 to 7 and are recorded in a separate review record. Go.
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | none | - | - |
 ---
 [PY-MIL-012]: ../../../src/flash_card/__init__.py
 [QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
 [7c1f1b6]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/7c1f1b6423a876d25afafd24f7f206d16ac6d669
@@ -0,0 +1,54 @@
 # RC-072: Review of the release v0.2.0
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-072 |
 | CrossReference | [MIL-012] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [5345fd7] |
 ---
 ## Artifact Under Review
 - Instance reviewed: [MIL-012] (the milestone's Go / No-Go criteria, checked against the release v0.2.0)
 - Checklist used: none exists for a release; the nine criteria of MIL-012 are the checklist
 - Scope: full review
 - Language and domain: n/a (record of results)
 - Language reviewer: none
 - Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | The three version places say `0.2.0` and a test fails when they differ | Pass | `pyproject.toml`, `flash_card.__version__` and `Doxyfile` say 0.2.0; `tests/unit/test_version.py` (3 tests) |
 | 2 | `CHANGELOG.md` has a `[0.2.0]` entry (menu bar, progress per word list, UTF-8 message) and `[0.1.0]` is unchanged | Pass | Read in the pull request #94 |
 | 3 | The upload limit of the git host is probed before the build with a draft release that is deleted afterwards, and the result is recorded | Pass | A draft release with a 1 MB random file was refused with `413 Request Entity Too Large`; the draft and its tag were deleted (release and tag lists checked) |
 | 4 | The executable is built with `--clean` from the commit to be tagged and passes the smoke test of MIL-009 | Fail | Built with `--clean` from `d7ca24d` (25.8 MB). The first smoke run passed three cases (level screen window, embedded list, progress file with 999 cards at level 100); the list override case failed once because the simulated mouse click did not register, and in 3 of 8 reruns the same click was lost. The cause was not found: it may be the click automation (timing of the pointer and the focus) or a defect of the program. The checks were stopped at the Product Owner's request because they take over the desktop, and are to be repeated in a container or on an isolated desktop (MIL-013) |
 | 5 | The tag `v0.2.0` is an annotated tag on that commit; `v0.1.0` is not moved | Fail | The tag points to `d7ca24d` and `v0.1.0` is unchanged (`2c580cc`), but the tag is lightweight: the push of my annotated tag failed on a connection error, and the release creation through the API then created a lightweight tag. Replacing it needs a force update of a tag, which is outside what an autonomous run may do without the Product Owner |
 | 6 | The release `v0.2.0` is published with notes (new, unsigned, `data` folder rule, how to build) | Pass | Release page returns HTTP 200; notes say what is new, that the file is unsigned, the `data` folder and how to build |
 | 7 | When the probe did not allow it: the notes say so and the issue "attach the files" stays open | Pass | The notes state that the executable is not attached and why; issue "Create the release and attach the files" stays open |
 | 8 | README, CHANGELOG and the Install page of the wiki in three languages link `v0.2.0`; `check-readme.sh` exit 0 | Pass | Merged in #94; wiki republished |
 | 9 | `pytest`, `ruff`, `mypy --strict`, `lint-imports` and `doxygen` are clean; BC-001, US-001 and PP-001 reviewed `Go` | Pass | 261 passed; RC-067 to RC-069 |
 ## Overall Verdict
 Go-with-conditions — the version, the CHANGELOG, the tag (lightweight) and the release page are in place, and the executable is correctly stated as not attached. Criteria 4 and 5 fail or are incomplete: the smoke test of the executable is not complete, and the tag is not annotated. Reviewed by AI as stand-in for S01; not independent of the author.
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | Decide whether the lightweight tag `v0.2.0` may be replaced by an annotated tag on the same commit (a force update of the tag on the host); `v0.1.0` stays | S01 | 2026-10-18 |
 | Repeat the smoke test of the executable on an isolated desktop or in a container and find the cause of the lost click (criterion 4), then close the issue "Build and smoke-test the executable" | S01 | 2026-10-21 |
 | Attach `flash-card.exe` and its checksum when the git host's upload limit is raised (issue "Create the release and attach the files") | S01 | 2026-10-21 |
 ---
 [MIL-012]: ../milestones/mil-012-release-0-2-0.md
 [5345fd7]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/5345fd77d404b7a8b7c3722fa5ada2bf14f234a7
@@ -0,0 +1,70 @@
 # RC-073: Review of BC-001
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-073 |
 | CrossReference | [BC-001], [QC-BC-001], [QC-LANG-001] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f86bc91] |
 ---
 ## Artifact Under Review
 - Instance reviewed: [BC-001]
 - Checklist used: [QC-BC-001], and [QC-LANG-001] (language and domain)
 - Scope: full review
 - Language and domain: en / it
 - Language reviewer: none (the stand-in for S01 reads the language and knows the domain)
 - Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | ROI/Cost-Benefit analysis is quantitative, or where qualitative, is explicitly justified | Pass | The Cost-Benefit table is qualitative and says why: no revenue is expected, so a quantitative return does not apply. |
 | 2 | Risks are identified with documented impact and mitigation | Pass | The Risks table has 5 risks, each with an impact and a mitigation. |
 | 3 | Success criteria are measurable, stating explicit targets rather than vague aspirations | Pass | The Success Criteria table has 8 rows with numeric targets and a measure each (for example 0 third-party packages; 5 commands or fewer). |
 | 4 | Scope explicitly separates In Scope vs Out of Scope | Pass | Scope has `### In Scope` and `### Out of Scope`; the container and sandbox checks are In Scope; macOS and other virtual machines are Out of Scope. |
 | 5 | Stakeholders are cross-referenced to Stakeholder Analysis IDs rather than re-described inline | Pass | The Stakeholders table cites S01, S02 and S03 and does not re-describe their roles. |
 | 6 | Methodology and quality-standard foundation are stated explicitly (e.g. ISO/IEC 25010, Larman) | Pass | Methodological and Standards Foundation names the framework, Larman, ISO/IEC 25010:2023 and PEP 8. |
 | 7 | Assumptions and constraints are explicit and clearly distinguished from one another | Pass | Assumptions and Constraints are separate sections. |
 | 8 | Document supports executive decision-making with a clear, unambiguous recommendation | Pass | Recommendation reads `Proceed` with a one-sentence rationale. |
 ## Language and Domain Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | The Metadata table has a `Language` row and a `Domain` row, and neither is a placeholder | Pass | Metadata of BC-001 has `Language | en` and `Domain | it`; neither is a placeholder. |
 | 2 | `Language` is a BCP 47 code and `Domain` is a value from the registry's domain list | Pass | `en` is a BCP 47 code and `it` is a value of the registry's domain list. |
 | 3 | The content (prose and table cells) is written in the stated language | Pass | Prose and table cells are English; Malay and Danish words and file names appear only as quoted data. |
 | 4 | The register matches the one the registry gives for the artifact type | Pass | The registry gives `IT Executive English` for this type; the text is written for that reader. |
 | 5 | Domain terms are the PO terms of the domain's dictionary, with no synonyms | Pass | The PO terms of DICT-001 (flash card, word list, words to learn, study session) are used and no synonym replaces them. |
 | 6 | Metadata keys, section headings, IDs and statuses are in English | Pass | Metadata keys, headings, IDs and statuses are English. |
 | 7 | No translated twin (`<name>.<language>.md`) exists beside the document | Pass | No translated twin exists beside the document (checked in `docs/`). |
 | 8 | A change of language or domain since the previous accepted version has a Version History row and was reviewed again | Pass | First version; no change of language or domain since an earlier accepted version. |
 | 9 | A reviewer competent in the domain, and in the language, has confirmed that the domain terms are used correctly | Pass | The reviewer is the stand-in for S01, the Product Owner, who reads English and knows the IT domain; no second language reviewer is needed (review-checklist-process step 2). Open to challenge by S01 in the end-of-run summary. |
 | 10 | Abbreviations are spelled out on first use, in the stated language | Fail | CSV, MVVM, UI, PO and similar abbreviations are not all spelled out at first use; Optional, deferred. |
 ## Overall Verdict
 Go — every Mandatory criterion passes; the failed Optional criteria are deferred with an action item. Reviewed by AI as stand-in for S01; not independent of the author.
 Full review (not a delta) after the change for MIL-013 (container and sandbox checks).
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | Criterion LANG 10 (Optional) failed: Abbreviations are spelled out on first use, in the stated language; fix or accept the deferral | S01 | 2026-10-21 |
 ---
 [BC-001]: ../../../docs/business-case.md
 [QC-BC-001]: ../../../framework/qc/artifacts/qc-business-case.md
 [QC-LANG-001]: ../../../framework/qc/artifacts/qc-language-domain.md
 [f86bc91]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f86bc9136e7719fbcd049a4f803959019b7d2df3
@@ -0,0 +1,54 @@
 # RC-074: Review of PP-001
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-074 |
 | CrossReference | [PP-001], [QC-LANG-001] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f86bc91] |
 ---
 ## Artifact Under Review
 - Instance reviewed: [PP-001]
 - Checklist used: none exists for this type, and [QC-LANG-001] (language and domain)
 - Scope: full review
 - Language and domain: en / it
 - Language reviewer: none (the stand-in for S01 reads the language and knows the domain)
 - Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
 ## Language and Domain Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | The Metadata table has a `Language` row and a `Domain` row, and neither is a placeholder | Pass | Metadata of PP-001 has `Language | en` and `Domain | it`; neither is a placeholder. |
 | 2 | `Language` is a BCP 47 code and `Domain` is a value from the registry's domain list | Pass | `en` is a BCP 47 code and `it` is a value of the registry's domain list. |
 | 3 | The content (prose and table cells) is written in the stated language | Pass | Prose and table cells are English; Malay and Danish words and file names appear only as quoted data. |
 | 4 | The register matches the one the registry gives for the artifact type | Pass | The registry gives `IT Executive English` for this type; the text is written for that reader. |
 | 5 | Domain terms are the PO terms of the domain's dictionary, with no synonyms | Pass | The PO terms of DICT-001 (flash card, word list, words to learn, study session) are used and no synonym replaces them. |
 | 6 | Metadata keys, section headings, IDs and statuses are in English | Pass | Metadata keys, headings, IDs and statuses are English. |
 | 7 | No translated twin (`<name>.<language>.md`) exists beside the document | Pass | No translated twin exists beside the document (checked in `docs/`). |
 | 8 | A change of language or domain since the previous accepted version has a Version History row and was reviewed again | Pass | First version; no change of language or domain since an earlier accepted version. |
 | 9 | A reviewer competent in the domain, and in the language, has confirmed that the domain terms are used correctly | Pass | The reviewer is the stand-in for S01, the Product Owner, who reads English and knows the IT domain; no second language reviewer is needed (review-checklist-process step 2). Open to challenge by S01 in the end-of-run summary. |
 | 10 | Abbreviations are spelled out on first use, in the stated language | Fail | CSV, MVVM, UI, PO and similar abbreviations are not all spelled out at first use; Optional, deferred. |
 ## Overall Verdict
 Go — no checklist exists for the Project Plan type; the plan now schedules MIL-013 on 2026-10-19 inside the Business Case constraint (delivery by 2026-10-21) and the language checklist passes. Accepted as the Product Owner's stand-in, after the Product Owner accepted the MIL-013 plan in chat. Reviewed by AI as stand-in for S01; not independent of the author.
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | Criterion LANG 10 (Optional) failed: Abbreviations are spelled out on first use, in the stated language; fix or accept the deferral | S01 | 2026-10-21 |
 ---
 [PP-001]: ../../../docs/project-plan.md
 [QC-LANG-001]: ../../../framework/qc/artifacts/qc-language-domain.md
 [f86bc91]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f86bc9136e7719fbcd049a4f803959019b7d2df3
@@ -0,0 +1,55 @@
 # RC-075: Review of ADR-0005
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-075 |
 | CrossReference | [ADR-0005], [QC-ADR-001] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f86bc91] |
 ---
 ## Artifact Under Review
 - Instance reviewed: [ADR-0005]
 - Checklist used: [QC-ADR-001]
 - Scope: full review
 - Language and domain: n/a (technical type)
 - Language reviewer: none
 - Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ID `ADR-0005` matches the file name number. |
 | 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | Context states the problem (the host desktop is taken over) and four options. |
 | 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Four options were considered. |
 | 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Decision is stated plainly and is option 2. |
 | 5 | Consequences list both Positive and Negative outcomes | Pass | Consequences have Positive and Negative lists. |
 | 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Portability, repeatability, image size and the weaker fallback are named. |
 | 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | Affected Artifacts BC-001 and ADR-0004 are listed and in CrossReference. |
 | 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | First version; no status change yet. |
 | 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | Not superseded or deprecated. |
 | 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | Written in plain technical English; product names are as the vendors write them. |
 | 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Status `Proposed` before this review; uses an allowed value. |
 ## Overall Verdict
 Go — every Mandatory criterion passes. Reviewed by AI as stand-in for S01; not independent of the author.
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | none | - | - |
 ---
 [ADR-0005]: ../../../docs/adr/adr-0005-container-and-sandbox-checks.md
 [QC-ADR-001]: ../../../framework/qc/artifacts/qc-adr.md
 [f86bc91]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f86bc9136e7719fbcd049a4f803959019b7d2df3
@@ -0,0 +1,66 @@
 # RC-076: Review of MIL-013
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-076 |
 | CrossReference | [MIL-013], [QC-MIL-001], [QC-LANG-001] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f86bc91] |
 ---
 ## Artifact Under Review
 - Instance reviewed: [MIL-013]
 - Checklist used: [QC-MIL-001], and [QC-LANG-001] (language and domain)
 - Scope: full review
 - Language and domain: en / it
 - Language reviewer: none (the stand-in for S01 reads the language and knows the domain)
 - Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | A concrete deliverable is defined for every gate | Pass | A concrete Deliverable section names the output evaluated at the gate. |
 | 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | The Go / No-Go table has numbered criteria, each with an observable Go and No-Go. |
 | 3 | Dependencies on other milestones are explicitly mapped | Pass | Dependencies table names the milestone or documents it needs. |
 | 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Traceability table maps to Business Case objectives and the user story. |
 | 5 | Milestone owner and approving reviewer are identified | Pass | Ownership table names S01 as owner and approving reviewer. |
 | 6 | Milestone has a defined target date consistent with project constraints | Pass | Target Date lies inside the 2026-10-14 to 2026-10-21 window of the Business Case. |
 ## Language and Domain Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | The Metadata table has a `Language` row and a `Domain` row, and neither is a placeholder | Pass | Metadata of MIL-013 has `Language | en` and `Domain | it`; neither is a placeholder. |
 | 2 | `Language` is a BCP 47 code and `Domain` is a value from the registry's domain list | Pass | `en` is a BCP 47 code and `it` is a value of the registry's domain list. |
 | 3 | The content (prose and table cells) is written in the stated language | Pass | Prose and table cells are English; Malay and Danish words and file names appear only as quoted data. |
 | 4 | The register matches the one the registry gives for the artifact type | Pass | The registry gives `IT Executive English` for this type; the text is written for that reader. |
 | 5 | Domain terms are the PO terms of the domain's dictionary, with no synonyms | Pass | The PO terms of DICT-001 (flash card, word list, words to learn, study session) are used and no synonym replaces them. |
 | 6 | Metadata keys, section headings, IDs and statuses are in English | Pass | Metadata keys, headings, IDs and statuses are English. |
 | 7 | No translated twin (`<name>.<language>.md`) exists beside the document | Pass | No translated twin exists beside the document (checked in `docs/`). |
 | 8 | A change of language or domain since the previous accepted version has a Version History row and was reviewed again | Pass | First version; no change of language or domain since an earlier accepted version. |
 | 9 | A reviewer competent in the domain, and in the language, has confirmed that the domain terms are used correctly | Pass | The reviewer is the stand-in for S01, the Product Owner, who reads English and knows the IT domain; no second language reviewer is needed (review-checklist-process step 2). Open to challenge by S01 in the end-of-run summary. |
 | 10 | Abbreviations are spelled out on first use, in the stated language | Fail | CSV, MVVM, UI, PO and similar abbreviations are not all spelled out at first use; Optional, deferred. |
 ## Overall Verdict
 Go — every Mandatory criterion passes; the failed Optional criteria are deferred with an action item. Reviewed by AI as stand-in for S01; not independent of the author.
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | Criterion LANG 10 (Optional) failed: Abbreviations are spelled out on first use, in the stated language; fix or accept the deferral | S01 | 2026-10-21 |
 ---
 [MIL-013]: ../../../docs/milestones/mil-013-container-checks.md
 [QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
 [QC-LANG-001]: ../../../framework/qc/artifacts/qc-language-domain.md
 [f86bc91]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f86bc9136e7719fbcd049a4f803959019b7d2df3
@@ -0,0 +1,64 @@
 # RC-077: Review of PY-MIL-013
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-077 |
 | CrossReference | [PY-MIL-013], [QC-PY-001] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f8ccfca] |
 ---
 ## Artifact Under Review
 - Instance reviewed: [PY-MIL-013]
 - Checklist used: [QC-PY-001]
 - Scope: full review
 - Language and domain: n/a (technical type)
 - Language reviewer: none
 - Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | PEP 8 casing holds in `smoke_driver.py`, `capture_screenshots.py` and the new tests; ruff rule set N passes. |
 | 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names state purpose (`known_button_point`, `parse_geometry`, `platform_kind`, `window_box`, `progress_ok`). |
 | 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff check` and `ruff format --check` pass on 83 files; the one `type: ignore` for `os.killpg` names the errors it silences. |
 | 4 | Every function and method signature is type-annotated, including `-> None` | Pass | Every signature is annotated; `mypy --strict` passes on 49 source files and on the four tool scripts. |
 | 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | Process start and stop failures are turned into a failed run with its reason, not swallowed; no bare `except`. |
 | 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults, no builtin shadowed. |
 | 7 | Files, locks and connections are managed with context managers | Pass | Temporary folders are context-managed or removed in `finally`; processes are stopped as a group. |
 | 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | Public modules, functions and constants have Doxygen docstrings; `doxygen Doxyfile` covers `src` and ends with 0 warnings. |
 | 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | Pass | No `print` in `src`; the tools write results with `sys.stdout.write` as JSON lines. |
 | 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | Pass | No program class changed; the tools are packaging and check support outside the design classes (ADR-0005). |
 | 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | 272 tests; the pure parts of the smoke driver and the capture tool are unit tested with fakes (no xdotool, no display); the whole suite passed twice in the Debian container including the real-window e2e tests. |
 | 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | `mypy --strict` reports no issue; no `Any`. |
 | 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | `dependencies` stays empty; the container image installs the extras `dev`, `speech`, `tools` and `build`. |
 | 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | The click point, the geometry parsing and the success rule are one function each in `smoke_driver.py`. |
 | 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | `lint-imports` reports `Layers point inward` kept; the tools import only the composition root. |
 | 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | Pure functions with injected `run`, `start` and `sleep`; no function mixes the platform choice with drawing. |
 | 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | `tools/docker/` holds the container scripts and the driver; the layers and the test folders are unchanged. |
 | 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | File and folder names follow the rule. |
 ## Overall Verdict
 Go — every Mandatory criterion passes. Reviewed by AI as stand-in for S01; not independent of the author.
 Reviewed in the Debian container (python:3.13-slim-bookworm, Python 3.13.16).
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | none | - | - |
 ---
 [PY-MIL-013]: ../../../tools
 [QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
 [f8ccfca]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f8ccfca02ef3a518eae472e3acdcd2aef03b5950
@@ -0,0 +1,61 @@
 # RC-078: Review of SH-MIL-013
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-078 |
 | CrossReference | [SH-MIL-013], [QC-SH-001] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f8ccfca] |
 ---
 ## Artifact Under Review
 - Instance reviewed: [SH-MIL-013]
 - Checklist used: [QC-SH-001]
 - Scope: full review
 - Language and domain: n/a (technical type)
 - Language reviewer: none
 - Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | Starts with `#!/usr/bin/env bash` and `set -euo pipefail` (or a comment explains the exception) | Pass | Every executable script starts with `#!/usr/bin/env bash` and `set -euo pipefail`; `start-desktop.sh` is sourced, says so in its header and sets no shell options in the caller. |
 | 2 | Every expansion is quoted; lists are arrays; tests use `[[ ]]` and `$(...)` | Pass | Expansions are quoted, tests use `[[ ]]`, command substitutions use `$(...)`; shellcheck reports nothing. |
 | 3 | Names follow the conventions: `kebab-case.sh` files, `snake_case` functions and variables, `UPPER_SNAKE` constants and environment variables | Pass | File names are kebab-case; variables are snake_case, environment variables UPPER_SNAKE. |
 | 4 | Passes `shellcheck` and `bash -n` with no unexplained `disable` comments | Pass | `shellcheck -x` and `bash -n` pass on all six scripts with no `disable` comment. |
 | 5 | Errors go to standard error with an `error:` message and a non-zero exit code; bad or missing arguments print a usage line | Pass | Errors go to standard error with `error:`, a usage line is printed, and bad arguments exit with 2 (`selftest.sh` checks it). |
 | 6 | Temporary files use `mktemp` with a `trap ... EXIT` cleanup; no fixed `/tmp` names | Pass | `start-desktop.sh` uses `mktemp -d` with a `trap ... EXIT`; no fixed `/tmp` names remain. |
 | 7 | No secret is written in the script, echoed, or put on a command line; secrets come from the environment or a gitignored file | Pass | No secret is used or written. |
 | 8 | A script that changes state outside its own directory defaults to a dry run or needs an explicit flag, and says so in its header | Pass | `in-container.sh` is the only script that deletes a folder; its header says so and it refuses the repository and `/` as work folder. |
 | 9 | A header comment states purpose, usage, options, environment variables and exit codes | Pass | Each header gives purpose, usage, environment, tools and exit codes. |
 | 10 | The script implements a task or design it cites; deviations are recorded | Pass | The scripts implement tasks 3, 4 and 6 of MIL-013 and ADR-0005; the fallback from GNOME Shell to mutter is recorded in the output. |
 | 11 | Behaviour is tested for success, failure and any disabled or bypass path | Pass | `selftest.sh` tests the refusals and `bash -n`; the success paths are the container runs of `run-checks.sh`, `screenshots.sh` and `smoke-binary.sh` (recorded in RC-079). |
 | 12 | Formatted with `shfmt` (or the project's formatter) | Fail | `shfmt` was not run; Optional, deferred. |
 | 13 | Safe to re-run: a second run does not duplicate or corrupt what the first did | Pass | The second container run gave the same result as the first (272 passed, 5 of 5 smoke runs). |
 | 14 | Bash version and external tools it needs are stated; GNU-only options are named | Pass | Bash and the external tools are listed under `Needs`; GNU `tar --exclude` is named by the tool list. |
 | 15 | A command sequence, constant, path or message used more than once is defined once (a function, a variable or a sourced helper); a helper is shared between scripts only where it expresses the same knowledge | Pass | The desktop start is defined once in `start-desktop.sh` and sourced by the three scripts. |
 ## Overall Verdict
 Go — every Mandatory criterion passes; the failed Optional criteria are deferred with an action item. Reviewed by AI as stand-in for S01; not independent of the author.
 Container run of the self test: 11 cases ok.
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | Criterion 12 (Optional) failed: Formatted with `shfmt` (or the project's formatter); fix or accept the deferral | S01 | 2026-10-21 |
 ---
 [SH-MIL-013]: ../../../tools/docker
 [QC-SH-001]: ../../../framework/qc/code/qc-programming-shell.md
 [f8ccfca]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f8ccfca02ef3a518eae472e3acdcd2aef03b5950
@@ -0,0 +1,54 @@
 # RC-079: Review of the container checks
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-079 |
 | CrossReference | [MIL-013] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [2f192b6] |
 ---
 ## Artifact Under Review
 - Instance reviewed: [MIL-013] (the milestone's Go / No-Go criteria, checked against the container and sandbox checks)
 - Checklist used: none exists for this result; the ten criteria of MIL-013 are the checklist
 - Scope: full review
 - Language and domain: n/a (record of results)
 - Language reviewer: none
 - Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | `docker build` of the Debian image succeeds | Pass | Image `flash-card-debian` built from `docker/debian.Dockerfile` (base `python:3.13-slim-bookworm`, Python 3.13.16); size 1697 MB; `binutils` was missing at first and was added after the first smoke build failed |
 | 2 | Linters and the whole test suite run on the virtual desktop and end with exit code 0, e2e tests not skipped | Pass | `run-checks.sh` twice: ruff, ruff format, mypy (49 files), lint-imports (1 kept) and 272 tests passed in 3.5 s; 33 s per run |
 | 3 | The full GNOME session is tried and the result recorded; fallback to mutter stated | Pass | `gnome-shell --x11` starts and then fails with `Gio.IOErrorEnum: Could not connect` in `LoginManagerSystemd` (no login manager in a container); the checks ran on GNOME's window manager mutter 43.8, which the script prints (`desktop: mutter on :99`) |
 | 4 | Nothing opens or moves on the host desktop during the runs | Pass | All runs of this record were `docker run` commands with no display; note: earlier unit runs of the test suite on the host by a helper agent opened Tk windows briefly before the Product Owner's instruction; from then on the suite ran only in the container |
 | 5 | The screenshot script writes the four PNG files from the Debian image | Pass | `screenshot-level.png`, `-front.png`, `-back.png`, `-menu.png` (20 to 23 KB each) written to the mounted folder and read by eye: the level screen, the card with the menu bar (File, About) are right |
 | 6 | The Linux binary is built and passes the smoke test 5 consecutive runs, and the source program too | Pass | `smoke-binary.sh 5` twice: the PyInstaller binary 5 of 5 (0.64 s per run) and `python -m flash_card` 5 of 5 (0.38 s); each run: window found, click at the known button (650, 659), progress file has header plus 2 cards |
 | 7 | The Windows executable passes the smoke test inside Windows Sandbox, 5 consecutive runs | Fail | Not run. `tools/sandbox/` (`flash-card.wsb`, `smoke.ps1`, `run.ps1`) is written, the PowerShell parses without errors and the configuration is well-formed XML, but starting Windows Sandbox opens a window on the host, and the Product Owner asked that no app runs on the development machine while working. The run waits for the Product Owner's go |
 | 8 | The lost-click symptom of RC-072 is investigated and the finding recorded | Pass | 10 of 10 presses of the known button registered in the container (binary and source). The symptom was seen only with the simulated Windows mouse (about 3 of 8 reruns) and is most likely a timing problem of that click automation (cursor move, focus, button down and up) and not a program defect; this is a finding for Linux only and it is not proven for Windows until criterion 7 is run |
 | 9 | README and the wiki Install page in three languages describe the commands and the limits; `check-readme.sh` exit 0 | Pass | Sections added; `check-readme.sh` exit 0; macOS stated as not covered, the Debian check stated as not a Windows check, the sandbox requirements stated |
 | 10 | BC-001, PP-001 and ADR-0005 are reviewed Go; code review has no failed Mandatory criterion | Pass | RC-073 to RC-076; RC-077 (Python) and RC-078 (shell) are Go |
 ## Overall Verdict
 Go-with-conditions — everything that can run without the host desktop runs and passes: the Debian checks (272 tests, linters), the screenshots, and the smoke test of the Linux binary and the source program. Criterion 7 (the Windows executable in Windows Sandbox) is not run and keeps the issue "Run and record the checks" open. Reviewed by AI as stand-in for S01; not independent of the author.
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | Run `powershell -File tools\sandbox\run.ps1 -Runs 5` after `python tools/build_executable.py` at a time that suits the Product Owner (Windows Sandbox shows its own window), and record the result in a new review record | S01 | 2026-10-21 |
 | Decide whether the GNOME Shell start in the container is worth a login-manager stub (it is not needed for the checks) | S01 | 2026-10-21 |
 ---
 [MIL-013]: ../milestones/mil-013-container-checks.md
 [2f192b6]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/2f192b6936a92f85c6c200de3cac3d6cf3572903
@@ -15,7 +15,8 @@
 | 2026-10-15 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added the rows and review records of the executable request (no checklist exists for this type) | [061b4f4] |
 | 2026-10-15 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added the rows and review records of the executable request (no checklist exists for this type) | [9c8e294] |
 | 2026-10-15 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added the rows and review records of the executable request (no checklist exists for this type) | [2211d0f] |
-| 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added the rows and review records of the executable request (no checklist exists for this type) | [0264b60] |
+| 2026-10-15 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added the rows and review records of the executable request (no checklist exists for this type) | [0264b60] |
 | 2026-10-15 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added the rows and review records of the executable request (no checklist exists for this type) | [f86bc91] |
 ---
@@ -29,9 +30,9 @@ updated whenever an artifact instance is created or reviewed.
 | Artifact Instance | Type | Language | Domain | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) |
 | --- | --- | --- | --- | --- | --- | --- |
-| BC-001 | Business Case | en | it | - | SA-001, PP-001 | [RC-067] |
+| BC-001 | Business Case | en | it | - | SA-001, PP-001 | [RC-073] |
 | SA-001 | Stakeholder Analysis | en | it | BC-001 | PP-001, DICT-001 | [RC-002] |
-| PP-001 | Project Plan | en | it | BC-001, SA-001 | MIL-001 to MIL-008 | [RC-069] |
+| PP-001 | Project Plan | en | it | BC-001, SA-001 | MIL-001 to MIL-008 | [RC-074] |
 | UCD-001 | Use Case Diagram | en | it | SA-001, BC-001 | US-001, UC-001 | [RC-004] |
 | US-001 | User Story | en | it | UCD-001, BC-001 | MIL-002 to MIL-006, MIL-008 | [RC-068] |
 | UC-001 | Use Case | en | it | UCD-001, US-001 | DM-001, SSD-001 | [RC-058] |
@@ -56,7 +57,9 @@ updated whenever an artifact instance is created or reviewed.
 | ADR-0004 | Architecture Decision Record | - | - | BC-001 | - | [RC-046] |
 | MIL-010 | Milestone / Gateway | en | it | BC-001 | - | [RC-054], [RC-055] |
 | MIL-011 | Milestone / Gateway | en | it | BC-001 | - | [RC-065] |
-| MIL-012 | Milestone / Gateway | en | it | BC-001 | - | [RC-070] |
+| MIL-012 | Milestone / Gateway | en | it | BC-001 | - | [RC-070], [RC-072] |
 | MIL-013 | Milestone / Gateway | en | it | BC-001 | - | [RC-076], [RC-079] |
 | ADR-0005 | Architecture Decision Record | - | - | BC-001 | - | [RC-075] |
 | PY-MIL-001 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-023] |
 | PY-MIL-002 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-024] |
 | PY-MIL-003 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-025] |
@@ -68,6 +71,9 @@ updated whenever an artifact instance is created or reviewed.
 | PY-MIL-009 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-048] |
 | PY-MIL-011 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-066] |
 | PY-FIX-001 | Python Source Code | - | - | PY-MIL-008 | - | [RC-049] |
 | PY-MIL-012 | Python Source Code | - | - | MIL-012 | - | [RC-071] |
 | PY-MIL-013 | Python Source Code | - | - | MIL-013 | - | [RC-077] |
 | SH-MIL-013 | Shell Script | - | - | MIL-013 | - | [RC-078] |
 ## Coverage Notes
@@ -193,3 +199,18 @@ updated whenever an artifact instance is created or reviewed.
 [RC-070]: ./reviews/rc-070-mil-012.md
 [MIL-012]: ../milestones/mil-012-release-0-2-0.md
 [0264b60]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/0264b6084f26bac5af716ea71596ce3be961fec8
 [RC-071]: ./reviews/rc-071-py-mil-012.md
 [PY-MIL-012]: ../../src/flash_card/__init__.py
 [RC-072]: ./reviews/rc-072-release-v0-2-0.md
 [RC-073]: ./reviews/rc-073-business-case-containers.md
 [RC-074]: ./reviews/rc-074-project-plan-containers.md
 [RC-075]: ./reviews/rc-075-adr-0005.md
 [RC-076]: ./reviews/rc-076-mil-013.md
 [MIL-013]: ../milestones/mil-013-container-checks.md
 [ADR-0005]: ../adr/adr-0005-container-and-sandbox-checks.md
 [f86bc91]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/f86bc9136e7719fbcd049a4f803959019b7d2df3
 [RC-077]: ./reviews/rc-077-py-mil-013.md
 [RC-078]: ./reviews/rc-078-sh-mil-013.md
 [PY-MIL-013]: ../../tools
 [SH-MIL-013]: ../../tools/docker
 [RC-079]: ./reviews/rc-079-container-checks.md
@@ -58,7 +58,7 @@ Vinduestesten i `tests/e2e/` springes over, når der ikke er en skærm.
 ## Udgivelse og programfil (Windows)
-[Udgivelsessiden](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.1.0) for v0.1.0 har udgivelsesnoterne. Programfilen er endnu ikke vedhæftet, fordi serverens grænse for upload afviser en fil af denne størrelse (HTTP 413); byg den som beskrevet nedenfor. Filen er ikke signeret, så Windows kan vise en SmartScreen-advarsel.
+Udgivelsessiderne for [v0.2.0](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.2.0) og [v0.1.0](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.1.0) har udgivelsesnoterne. Programfilen er endnu ikke vedhæftet, fordi serverens grænse for upload afviser en fil af denne størrelse (HTTP 413); byg den som beskrevet nedenfor. Filen er ikke signeret, så Windows kan vise en SmartScreen-advarsel.
 ## Byg en programfil (Windows)
@@ -74,6 +74,26 @@ Scriptet bruger PyInstaller og skriver `dist/flash-card.exe`: én fil uden konso
 - `python tools/build_executable.py --no-speech` udelader talepakkerne; `--clean` bygger forfra.
 - Programfilen er ikke i repositoryet. Byg den på det system, hvor den skal køre; Windows kan vise en SmartScreen-advarsel, fordi filen ikke er signeret.
 ## Kontroller uden skrivebord (Docker)
 Testene, linterne, skærmbillederne og en røgtest af en Linux-binær kører i en Debian-container på en virtuel skærm, så der ikke åbnes noget vindue på dit eget skrivebord.
 ```bash
 docker build -f docker/debian.Dockerfile -t flash-card-debian .
 # linters og hele testsuiten, også testene af det rigtige vindue
 docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh run-checks.sh
 # skærmbilleder til ./build/container-out
 docker run --rm -v "$PWD:/repo:ro" -v "$PWD/build/container-out:/out" flash-card-debian bash /repo/tools/docker/in-container.sh screenshots.sh /out
 # byg Linux-binæren og tryk på "kender" 5 gange (binær og kildekode)
 docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh smoke-binary.sh 5
 ```
 I Windows PowerShell skriver du `${PWD}` i stedet for `$PWD`. Repositoryet monteres skrivebeskyttet og kopieres inde i containeren.
 - Skrivebordet er Xvfb med GNOMEs vindueshåndtering (mutter). GNOME Shell prøves først og starter ikke i en container (den kræver en login-manager), så scripts falder tilbage til mutter og skriver hvilken der kørte.
 - Windows-programfilen kontrolleres i **Windows Sandbox** (Windows 11 Pro, funktionen aktiveret): `powershell -File tools\sandbox\run.ps1 -Runs 5` efter `python tools/build_executable.py`. Sandboxen viser sit eget vindue, mens den kører; klikket sker inde i sandboxen.
 - Ikke dækket: macOS (kan ikke køres i Docker på Windows eller Linux, og Apples licens tillader det kun på Apple-hardware), og selve Windows i Debian-containeren.
 ## Dokumentation af kildekoden
 ```bash
@@ -58,7 +58,7 @@ Ujian tetingkap dalam `tests/e2e/` dilangkau apabila tiada paparan.
 ## Keluaran dan fail boleh laku (Windows)
-[Halaman keluaran](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.1.0) v0.1.0 mempunyai nota keluaran. Fail boleh laku belum dilampirkan di sana kerana had muat naik pelayan menolak fail sebesar ini (HTTP 413); bina seperti yang diterangkan di bawah. Fail tidak ditandatangani, jadi Windows mungkin menunjukkan amaran SmartScreen.
+Halaman keluaran [v0.2.0](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.2.0) dan [v0.1.0](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.1.0) mempunyai nota keluaran. Fail boleh laku belum dilampirkan di sana kerana had muat naik pelayan menolak fail sebesar ini (HTTP 413); bina seperti yang diterangkan di bawah. Fail tidak ditandatangani, jadi Windows mungkin menunjukkan amaran SmartScreen.
 ## Bina fail boleh laku (Windows)
@@ -74,6 +74,26 @@ Skrip menggunakan PyInstaller dan menulis `dist/flash-card.exe`: satu fail tanpa
 - `python tools/build_executable.py --no-speech` meninggalkan pakej suara; `--clean` membina semula dari awal.
 - Fail boleh laku tidak disimpan dalam repositori. Bina di sistem tempat ia akan dijalankan; Windows mungkin menunjukkan amaran SmartScreen kerana fail tidak ditandatangani.
 ## Semakan tanpa desktop (Docker)
 Ujian, linter, tangkapan skrin dan ujian asap bagi binari Linux dijalankan dalam kontena Debian pada skrin maya, jadi tiada tetingkap dibuka pada desktop anda sendiri.
 ```bash
 docker build -f docker/debian.Dockerfile -t flash-card-debian .
 # linter dan seluruh suite ujian, termasuk ujian tetingkap sebenar
 docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh run-checks.sh
 # tangkapan skrin ke ./build/container-out
 docker run --rm -v "$PWD:/repo:ro" -v "$PWD/build/container-out:/out" flash-card-debian bash /repo/tools/docker/in-container.sh screenshots.sh /out
 # bina binari Linux dan tekan butang "tahu" 5 kali (binari dan kod sumber)
 docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh smoke-binary.sh 5
 ```
 Dalam Windows PowerShell tulis `${PWD}` untuk `$PWD`. Repositori dipasang baca sahaja dan disalin di dalam kontena.
 - Desktop ialah Xvfb dengan pengurus tetingkap GNOME (mutter). GNOME Shell dicuba dahulu dan tidak bermula dalam kontena (ia memerlukan pengurus log masuk), jadi skrip beralih kepada mutter dan mencetak yang mana dijalankan.
 - Fail boleh laku Windows disemak dalam **Windows Sandbox** (Windows 11 Pro, ciri diaktifkan): `powershell -File tools\sandbox\run.ps1 -Runs 5` selepas `python tools/build_executable.py`. Sandbox menunjukkan tetingkapnya sendiri semasa berjalan; klik dibuat di dalam sandbox.
 - Tidak dilindungi: macOS (tidak boleh dijalankan dalam Docker pada Windows atau Linux dan lesen Apple hanya membenarkannya pada perkakasan Apple), dan Windows sebenar dalam kontena Debian.
 ## Dokumentasi kod sumber
 ```bash
@@ -58,7 +58,7 @@ The window test in `tests/e2e/` is skipped when no display is available.
 ## Release and executable (Windows)
-The [release page](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.1.0) of v0.1.0 has the release notes. The executable is not attached there yet, because the server's upload limit rejects a file of this size (HTTP 413); build it as described below. The file is not signed, so Windows may show a SmartScreen warning.
+The release pages of [v0.2.0](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.2.0) and [v0.1.0](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.1.0) have the release notes. The executable is not attached there yet, because the server's upload limit rejects a file of this size (HTTP 413); build it as described below. The file is not signed, so Windows may show a SmartScreen warning.
 ## Build an executable (Windows)
@@ -74,6 +74,26 @@ The script uses PyInstaller and writes `dist/flash-card.exe`: one file, no conso
 - `python tools/build_executable.py --no-speech` leaves the speech packages out; `--clean` rebuilds from scratch.
 - The executable is not committed to the repository. Build it on the system you want to run it on; Windows may show a SmartScreen warning because the file is not signed.
 ## Checks without a desktop (Docker)
 The tests, the linters, the screenshots and a smoke test of a Linux binary run in a Debian container on a virtual screen, so no window opens on your own desktop.
 ```bash
 docker build -f docker/debian.Dockerfile -t flash-card-debian .
 # linters and the whole test suite, including the real window tests
 docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh run-checks.sh
 # screenshots into ./build/container-out
 docker run --rm -v "$PWD:/repo:ro" -v "$PWD/build/container-out:/out" flash-card-debian bash /repo/tools/docker/in-container.sh screenshots.sh /out
 # build the Linux binary and press the known button 5 times (binary and source)
 docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh smoke-binary.sh 5
 ```
 On Windows PowerShell write `${PWD}` for `$PWD`. The repository is mounted read-only and copied inside the container.
 - The desktop is Xvfb with GNOME's window manager (mutter). GNOME Shell is tried first and does not start in a container (it needs a login manager), so the scripts fall back to mutter and print which one ran.
 - The Windows executable is checked in **Windows Sandbox** (Windows 11 Pro, feature enabled): `powershell -File tools\sandbox\run.ps1 -Runs 5` after `python tools/build_executable.py`. The sandbox shows its own window while it runs; the click is made inside the sandbox.
 - Not covered: macOS (it cannot be run in Docker on Windows or Linux and Apple's licence allows it only on Apple hardware), and Windows itself in the Debian container.
 ## Documentation of the source code
 ```bash
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "flash-card"
-version = "0.1.0"
+version = "0.2.0"
 description = "Flash card program for learning Malay words with Danish translations (Udemy 100 Days of Code, day 31)"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -4,4 +4,4 @@
@brief Package root of the flash card program.
 """
-__version__ = "0.1.0"
+__version__ = "0.2.0"
@@ -0,0 +1,41 @@
 """Tests of the pure parts of the screenshot tool.
@file test_capture_screenshots.py
@brief Checks platform_kind and window_box of tools/capture_screenshots.py.
 """
 import importlib.util
 from pathlib import Path
 from types import ModuleType
 import pytest
 pytest.importorskip("PIL")
 _TOOL_PATH = Path(__file__).resolve().parents[2] / "tools" / "capture_screenshots.py"
 def _load_tool() -> ModuleType:
    spec = importlib.util.spec_from_file_location("capture_screenshots", _TOOL_PATH)
    assert spec is not None
    assert spec.loader is not None
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module
 def test_platform_kind_is_windows_for_win32() -> None:
    assert _load_tool().platform_kind("win32") == "windows"
 def test_platform_kind_is_x11_for_linux() -> None:
    assert _load_tool().platform_kind("linux") == "x11"
 def test_window_box_adds_menu_height_on_x11() -> None:
    assert _load_tool().window_box("x11", 10, 100, 900, 726, 28) == (10, 72, 910, 826)
 def test_window_box_ignores_menu_height_on_windows() -> None:
    box = _load_tool().window_box("windows", 10, 100, 900, 726, 28)
    assert box == (10, 100, 910, 826)
@@ -0,0 +1,122 @@
 """Tests of the smoke driver tool.
@file test_smoke_driver.py
@brief Checks the pure helpers and the run loop of tools/docker/smoke_driver.py
 with a fake xdotool and a fake program.
 """
 import importlib.util
 import json
 import sys
 from collections.abc import Sequence
 from pathlib import Path
 from types import ModuleType
 import pytest
 _TOOL_PATH = (
    Path(__file__).resolve().parents[2] / "tools" / "docker" / "smoke_driver.py"
 )
 _GEOMETRY = "WINDOW=7\nX=0\nY=0\nWIDTH=900\nHEIGHT=800\nSCREEN=0\n"
 def _load_tool() -> ModuleType:
    spec = importlib.util.spec_from_file_location("smoke_driver", _TOOL_PATH)
    assert spec is not None
    assert spec.loader is not None
    module = importlib.util.module_from_spec(spec)
    # dataclasses looks the module up by name while the class is built
    sys.modules[spec.name] = module
    spec.loader.exec_module(module)
    return module
 class _FakeProgram:
    def __init__(self) -> None:
        self.stopped = False
    def stop(self) -> None:
        self.stopped = True
 class _FakeSystem:
    """Fake xdotool and program; a click writes the progress file."""
    def __init__(self, has_window: bool, writes_progress: bool) -> None:
        self.has_window = has_window
        self.writes_progress = writes_progress
        self.program = _FakeProgram()
        self.data_dir: Path | None = None
    def start(self, command: Sequence[str]) -> _FakeProgram:
        self.data_dir = Path(command[command.index("--data-dir") + 1])
        return self.program
    def run(self, args: Sequence[str]) -> str:
        if args[1] == "search":
            return "7\n" if self.has_window else ""
        if args[1] == "getwindowgeometry":
            return _GEOMETRY
        if args[1] == "mousemove" and self.writes_progress:
            assert self.data_dir is not None
            progress = self.data_dir / "words_to_learn.csv"
            progress.write_text("ms;da\nw1;t1\nw2;t2\n", encoding="utf-8")
        return ""
 def test_known_button_point_is_101_above_bottom() -> None:
    assert _load_tool().known_button_point(900, 800) == (650, 699)
 def test_words_file_text_has_header_and_cards() -> None:
    assert _load_tool().words_file_text(2) == "ms;da\nw1;t1\nw2;t2\n"
 def test_parse_geometry_reads_width_and_height() -> None:
    assert _load_tool().parse_geometry(_GEOMETRY) == (900, 800)
 def test_parse_geometry_fails_without_size() -> None:
    with pytest.raises(ValueError):
        _load_tool().parse_geometry("X=0\n")
 def test_progress_ok_needs_exactly_one_card_less() -> None:
    tool = _load_tool()
    assert tool.progress_ok(3, 3)
    assert not tool.progress_ok(4, 3)
    assert not tool.progress_ok(0, 3)
 def test_main_returns_zero_when_click_saves_progress(
    capsys: pytest.CaptureFixture[str],
 ) -> None:
    system = _FakeSystem(has_window=True, writes_progress=True)
    code = _load_tool().main(
        ["--repeat", "2", "--words", "3", "--command", "prog", "-m", "x"],
        run=system.run,
        start=system.start,
        sleep=lambda _: None,
    )
    lines = [json.loads(x) for x in capsys.readouterr().out.splitlines()]
    assert code == 0
    assert lines[0]["ok"] is True
    assert lines[0]["clicked"] == [650, 699]
    assert lines[-1] == {"runs": 2, "passed": 2}
    assert system.program.stopped
 def test_main_fails_when_no_window_appears(
    capsys: pytest.CaptureFixture[str],
 ) -> None:
    system = _FakeSystem(has_window=False, writes_progress=False)
    code = _load_tool().main(
        ["--repeat", "1", "--timeout", "1", "--command", "prog"],
        run=system.run,
        start=system.start,
        sleep=lambda _: None,
    )
    first = json.loads(capsys.readouterr().out.splitlines()[0])
    assert code == 1
    assert first["window"] is False
    assert system.program.stopped
@@ -0,0 +1,35 @@
 """Keep the version declared in code, pyproject.toml and the Doxyfile in step.
@file test_version.py
@brief Unit tests that the three version declarations cannot drift.
 """
 import re
 import tomllib
 import flash_card
 from flash_card.constants import PROJECT_ROOT
 _SEMVER_PATTERN = re.compile(r"^\d+\.\d+\.\d+$")
 _PROJECT_NUMBER_PATTERN = re.compile(r"^PROJECT_NUMBER\s*=\s*(\S+)\s*$", re.MULTILINE)
 def _pyproject_version() -> str:
    with (PROJECT_ROOT / "pyproject.toml").open("rb") as file:
        version: str = tomllib.load(file)["project"]["version"]
    return version
 def test_version_matches_package_version_when_read_from_pyproject() -> None:
    assert _pyproject_version() == flash_card.__version__
 def test_version_has_major_minor_patch_form() -> None:
    assert _SEMVER_PATTERN.match(flash_card.__version__) is not None
 def test_version_matches_doxyfile_project_number() -> None:
    text = (PROJECT_ROOT / "Doxyfile").read_text(encoding="utf-8")
    match = _PROJECT_NUMBER_PATTERN.search(text)
    assert match is not None
    assert match.group(1) == flash_card.__version__
@@ -13,7 +13,7 @@ from __future__ import annotations
 import argparse
 import ctypes
-import ctypes.wintypes
+import os
 import random
 import shutil
 import sys
@@ -23,7 +23,7 @@ import tkinter as tk
 from collections.abc import Sequence
 from pathlib import Path
-from PIL import ImageGrab
+from PIL import Image, ImageGrab
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
@@ -45,6 +45,46 @@ DEFAULT_OUTPUT_DIR = PROJECT_ROOT / "docs" / "images"
 SCREENSHOT_SEED = 7
 ## @brief Extra time in seconds to let the window settle before a grab.
 SETTLE_SECONDS = 0.5
 ## @brief Height in pixels of the menu bar above the client area on X11.
 MENU_BAR_HEIGHT_X11 = 28
 ## @brief Platform kind of Windows.
 KIND_WINDOWS = "windows"
 ## @brief Platform kind of every other platform (an X11 display).
 KIND_X11 = "x11"
 def platform_kind(platform: str) -> str:
    """Choose how to grab the screen.
    @param platform A `sys.platform` value.
    @return "windows" for win32, otherwise "x11".
    """
    return KIND_WINDOWS if platform == "win32" else KIND_X11
 def window_box(
    kind: str, rootx: int, rooty: int, width: int, height: int, menu_height: int
 ) -> tuple[int, int, int, int]:
    """Return the screen box to grab for a window.
    @param kind The platform kind from `platform_kind`.
    @param rootx Left edge of the client area.
    @param rooty Top edge of the client area.
    @param width Width of the client area.
    @param height Height of the client area.
    @param menu_height Height of the menu bar above the client area; it is
        added on X11 only, as on Windows the frame box is read from the system.
    @return Left, top, right and bottom in screen pixels.
    """
    top = rooty - menu_height if kind == KIND_X11 else rooty
    return rootx, top, rootx + width, rooty + height
 def _grab(box: tuple[int, int, int, int]) -> Image.Image:
    """Grab a screen box on the current platform."""
    if platform_kind(sys.platform) == KIND_X11:
        return ImageGrab.grab(bbox=box, xdisplay=os.environ.get("DISPLAY"))
    return ImageGrab.grab(bbox=box)
 def _make_dpi_aware() -> None:
@@ -59,6 +99,8 @@ def _frame_box(root: tk.Tk) -> tuple[int, int, int, int]:
    @param root The Tk root window.
    @return Left, top, right and bottom in screen pixels.
    """
    import ctypes.wintypes  # Windows only, so it is imported here
    handle = ctypes.windll.user32.GetParent(root.winfo_id())  # type: ignore[attr-defined,unused-ignore]
    rect = ctypes.wintypes.RECT()
    ctypes.windll.user32.GetWindowRect(handle, ctypes.byref(rect))  # type: ignore[attr-defined,unused-ignore]
@@ -102,13 +144,14 @@ def capture(output_dir: Path) -> list[Path]:
        root.lift()
        root.attributes("-topmost", True)
        _pump(root, SETTLE_SECONDS)
-        window_box = (
+        kind = platform_kind(sys.platform)
        client = (
            root.winfo_rootx(),
            root.winfo_rooty(),
-            root.winfo_rootx() + root.winfo_width(),
+            root.winfo_width(),
-            root.winfo_rooty() + root.winfo_height(),
+            root.winfo_height(),
        )
-        ImageGrab.grab(bbox=window_box).save(level)
+        _grab(window_box(kind, *client, 0)).save(level)
        application.start(Level(None))
        view = application.view
        if not isinstance(view, FlashCardView):
@@ -123,10 +166,14 @@ def capture(output_dir: Path) -> list[Path]:
            + view.right_button.winfo_height()
            + 20,
        )
-        ImageGrab.grab(bbox=box).save(front)
+        _grab(box).save(front)
-        ImageGrab.grab(bbox=_frame_box(root)).save(menu)
+        if kind == KIND_WINDOWS:
            menu_box = _frame_box(root)
        else:
            menu_box = window_box(kind, *client, MENU_BAR_HEIGHT_X11)
        _grab(menu_box).save(menu)
        _pump(root, FLIP_DELAY_MS / 1000 + SETTLE_SECONDS)
-        ImageGrab.grab(bbox=box).save(back)
+        _grab(box).save(back)
        root.destroy()
    return [level, front, back, menu]
@@ -0,0 +1,50 @@
 #!/usr/bin/env bash
 # Run one of the check scripts on a COPY of the repository, so that the
 # mounted repository stays untouched (no build/, dist/ or caches in it).
 #
 # Purpose:  isolate the checks from the host (ADR-0005).
 # Usage:    in-container.sh <script> [args...]
 #             in-container.sh run-checks.sh
 #             in-container.sh screenshots.sh /out
 #             in-container.sh smoke-binary.sh 5
 # Env:      REPO_DIR (default /repo, mounted read-only), WORK_DIR (default
 #           $HOME/work; it is deleted and recreated, so it must be a folder of
 #           the container, never the mounted repository)
 # Needs:    bash 5, tar
 # Exit:     2 on bad arguments or a missing script; else the exit code of the
 #           script that was run
 set -euo pipefail
 repo="${REPO_DIR:-/repo}"
 work="${WORK_DIR:-${HOME}/work}"
 usage() {
  echo "usage: in-container.sh <script> [args...]" >&2
  echo "scripts: run-checks.sh screenshots.sh smoke-binary.sh" >&2
 }
 if [[ $# -lt 1 ]]; then
  usage
  exit 2
 fi
 script="$1"
 shift
 if [[ ! -f "${repo}/tools/docker/${script}" ]]; then
  echo "error: no such script: tools/docker/${script}" >&2
  usage
  exit 2
 fi
 if [[ "${work}" == "${repo}" || "${work}" == "/" ]]; then
  echo "error: WORK_DIR must not be the repository or /" >&2
  exit 2
 fi
 rm -rf "${work}"
 mkdir -p "${work}"
 tar -C "${repo}" \
  --exclude=.git --exclude=.venv --exclude=build --exclude=dist \
  --exclude=docs/doxygen --exclude=.codex --exclude='__pycache__' \
  -cf - . | tar -C "${work}" -xf -
 cd "${work}"
 export PYTHONPATH="${work}/src"
 exec bash "tools/docker/${script}" "$@"
@@ -0,0 +1,21 @@
 #!/usr/bin/env bash
 # Run the linters and the whole test suite (with the e2e tests of the real Tk
 # window) on the virtual desktop.
 #
 # Purpose:  the quality gate without a desktop of the host (ADR-0005).
 # Usage:    run-checks.sh        (from the repository root, via in-container.sh)
 # Env:      see start-desktop.sh
 # Needs:    ruff, mypy, import-linter, pytest (the dev extra), the desktop
 # Exit:     0 only when every check passes
 set -euo pipefail
 cd "$(dirname "${BASH_SOURCE[0]}")/../.."
 # shellcheck source=tools/docker/start-desktop.sh
 . tools/docker/start-desktop.sh
 python -m ruff check src tests tools
 python -m ruff format --check src tests tools
 python -m mypy
 lint-imports
 python -m pytest -ra -q
 echo "checks passed on desktop: ${DESKTOP_KIND}"
@@ -0,0 +1,19 @@
 #!/usr/bin/env bash
 # Take the screenshots (level screen, card front, card back, window with the
 # menu bar) on the virtual desktop.
 #
 # Purpose:  screenshots without a desktop of the host (ADR-0005).
 # Usage:    screenshots.sh [output-folder]      (default /out)
 # Env:      see start-desktop.sh
 # Needs:    Pillow (the tools extra), the desktop
 # Exit:     0 when the four files were written; else the tool's exit code
 set -euo pipefail
 cd "$(dirname "${BASH_SOURCE[0]}")/../.."
 # shellcheck source=tools/docker/start-desktop.sh
 . tools/docker/start-desktop.sh
 out="${1:-/out}"
 mkdir -p "${out}"
 python tools/capture_screenshots.py --output-dir "${out}"
 ls -l "${out}"
@@ -0,0 +1,37 @@
 #!/usr/bin/env bash
 # Tests of the check scripts themselves: argument errors and refusals. The
 # success paths are the runs of run-checks.sh, screenshots.sh and
 # smoke-binary.sh.
 #
 # Purpose:  QC-SH-001 criterion 11 (success, failure and bypass paths).
 # Usage:    selftest.sh          (from the repository root)
 # Needs:    bash 5
 # Exit:     0 when every case behaves as stated; 1 when one differs
 set -euo pipefail
 cd "$(dirname "${BASH_SOURCE[0]}")/../.."
 fail=0
 expect_exit() {
  local expected="$1" label="$2"
  shift 2
  local code=0
  "$@" >/dev/null 2>&1 || code=$?
  if [[ "${code}" -ne "${expected}" ]]; then
    echo "FAIL: ${label}: exit ${code}, expected ${expected}" >&2
    fail=1
  else
    echo "ok: ${label}"
  fi
 }
 expect_exit 2 "in-container without arguments" bash tools/docker/in-container.sh
 expect_exit 2 "in-container with an unknown script" bash tools/docker/in-container.sh nope.sh
 expect_exit 2 "in-container refuses the repository as work folder" \
  env REPO_DIR="$(pwd)" WORK_DIR="$(pwd)" bash tools/docker/in-container.sh run-checks.sh
 expect_exit 2 "smoke-binary with a text count" bash tools/docker/smoke-binary.sh many
 expect_exit 2 "smoke-binary with zero" bash tools/docker/smoke-binary.sh 0
 for script in start-desktop run-checks screenshots smoke-binary in-container selftest; do
  expect_exit 0 "bash -n ${script}.sh" bash -n "tools/docker/${script}.sh"
 done
 exit "${fail}"
@@ -0,0 +1,31 @@
 #!/usr/bin/env bash
 # Build the Linux binary with PyInstaller and smoke-test it, and the source
 # program, on the virtual desktop. The smoke test starts the program, finds the
 # window, presses the known button with the virtual mouse of the desktop and
 # checks the progress file.
 #
 # Purpose:  the "does the packaged program work" check without a desktop of the
 #           host (ADR-0005, RC-072).
 # Usage:    smoke-binary.sh [repeat-count]      (default 5)
 # Env:      see start-desktop.sh
 # Needs:    pyinstaller (the build extra), binutils, xdotool, the desktop
 # Exit:     0 only when every run of both programs passes; 2 on a bad count
 set -euo pipefail
 repeat="${1:-5}"
 if ! [[ "${repeat}" =~ ^[1-9][0-9]*$ ]]; then
  echo "error: repeat-count must be a positive integer, got '${repeat}'" >&2
  echo "usage: smoke-binary.sh [repeat-count]" >&2
  exit 2
 fi
 cd "$(dirname "${BASH_SOURCE[0]}")/../.."
 # shellcheck source=tools/docker/start-desktop.sh
 . tools/docker/start-desktop.sh
 python tools/build_executable.py --clean
 test -x dist/flash-card
 echo "== binary"
 python tools/docker/smoke_driver.py --repeat "${repeat}" --command dist/flash-card
 echo "== source"
 python tools/docker/smoke_driver.py --repeat "${repeat}" --command python -m flash_card
@@ -0,0 +1,252 @@
 """Smoke driver that clicks the known button of the running program.
@file smoke_driver.py
@brief Starts the program on the current X display, finds its window with
 xdotool, clicks the tick button and checks that one card was saved as known.
 Uses the standard library only, so it runs in a bare container. It needs
 `xdotool` and a DISPLAY. Exit code 0 only when every run is ok.
 """
 from __future__ import annotations
 import argparse
 import json
 import os
 import shutil
 import signal
 import subprocess
 import sys
 import tempfile
 import time
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Protocol
 ## @brief Title of the program window.
 WINDOW_NAME = "Flashy"
 ## @brief X of the tick button, in window pixels.
 KNOWN_BUTTON_X = 650
 ## @brief Distance of the tick button centre above the bottom window edge.
 KNOWN_BUTTON_BOTTOM_OFFSET = 101
 ## @brief Seconds between two polls.
 POLL_SECONDS = 0.25
 ## @brief Seconds to wait for the progress file after the click.
 PROGRESS_TIMEOUT_SECONDS = 5.0
 ## @brief Name of the vocabulary file written for a run.
 VOCABULARY_NAME = "ms-da.csv"
 ## @brief Name of the progress file the program writes.
 PROGRESS_NAME = "words_to_learn.csv"
 class Running(Protocol):
    """A started program that can be stopped."""
    def stop(self) -> None:
        """Stop the program and its children."""
 ## @brief Runs a command and returns its stdout ("" when it fails).
 RunCommand = Callable[[Sequence[str]], str]
 ## @brief Starts the program and returns a handle to stop it.
 StartProgram = Callable[[Sequence[str]], Running]
 ## @brief Waits for a number of seconds.
 Sleep = Callable[[float], None]
 def known_button_point(width: int, height: int) -> tuple[int, int]:
    """Return the click point of the known button inside the window.
    @param width Window width in pixels (the button x is fixed).
    @param height Window height in pixels.
    @return X and Y relative to the window.
    """
    return KNOWN_BUTTON_X, height - KNOWN_BUTTON_BOTTOM_OFFSET
 def words_file_text(count: int) -> str:
    """Return the text of a vocabulary file with count cards.
    @param count Number of cards.
    @return A `ms;da` header and the lines `w1;t1`, `w2;t2`, ...
    """
    lines = ["ms;da", *(f"w{i};t{i}" for i in range(1, count + 1))]
    return "\n".join(lines) + "\n"
 def parse_geometry(shell_output: str) -> tuple[int, int]:
    """Read the size from `xdotool getwindowgeometry --shell`.
    @param shell_output The KEY=VALUE lines.
    @return Width and height.
    @throws ValueError When WIDTH or HEIGHT is missing.
    """
    values: dict[str, int] = {}
    for line in shell_output.splitlines():
        key, _, value = line.partition("=")
        if key in ("WIDTH", "HEIGHT") and value.strip().isdigit():
            values[key] = int(value)
    if "WIDTH" not in values or "HEIGHT" not in values:
        raise ValueError("no WIDTH and HEIGHT in the geometry output")
    return values["WIDTH"], values["HEIGHT"]
 def progress_ok(rows: int, words: int) -> bool:
    """Tell whether the progress file shows exactly one card known.
    @param rows Lines in the progress file, the header included.
    @param words Cards at the start.
    @return True when the file has the header and words - 1 cards.
    """
    return rows == words
 class _Process:
    """A real subprocess, stopped as a whole process group."""
    def __init__(self, process: subprocess.Popen[bytes]) -> None:
        self._process = process
    def stop(self) -> None:
        """Terminate the process group, then kill it if it stays."""
        try:
            os.killpg(self._process.pid, signal.SIGTERM)  # type: ignore[attr-defined,unused-ignore]
            self._process.wait(timeout=3)
        except (ProcessLookupError, subprocess.TimeoutExpired):
            self._process.kill()
 def real_run(args: Sequence[str]) -> str:
    """Run a command and return stdout, or "" when it fails."""
    try:
        done = subprocess.run(args, capture_output=True, text=True, check=False)
    except OSError:
        return ""
    return done.stdout if done.returncode == 0 else ""
 def real_start(command: Sequence[str]) -> Running:
    """Start the program in its own process group."""
    return _Process(subprocess.Popen(command, start_new_session=True))
@dataclass(frozen=True)
 class RunResult:
    """The outcome of one run."""
    window: bool
    clicked: tuple[int, int] | None
    progress_rows: int
    ok: bool
 def _count_rows(path: Path) -> int:
    if not path.exists():
        return 0
    return len(path.read_text(encoding="utf-8").splitlines())
 def _wait_for_window(run: RunCommand, sleep: Sleep, timeout: float) -> str | None:
    waited = 0.0
    while True:
        found = run(["xdotool", "search", "--name", WINDOW_NAME]).split()
        if found:
            return found[0]
        if waited >= timeout:
            return None
        sleep(POLL_SECONDS)
        waited += POLL_SECONDS
 def _wait_for_progress(path: Path, sleep: Sleep) -> int:
    waited = 0.0
    rows = _count_rows(path)
    while rows == 0 and waited < PROGRESS_TIMEOUT_SECONDS:
        sleep(POLL_SECONDS)
        waited += POLL_SECONDS
        rows = _count_rows(path)
    return rows
 def run_once(
    command: Sequence[str],
    words: int,
    timeout: float,
    run: RunCommand,
    start: StartProgram,
    sleep: Sleep = time.sleep,
 ) -> RunResult:
    """Start the program, click the known button and check the progress file.
    @param command The program command.
    @param words Number of cards in the vocabulary.
    @param timeout Seconds to wait for the window.
    @param run Runs xdotool.
    @param start Starts the program.
    @param sleep Waits between polls.
    @return The result of the run.
    """
    folder = Path(tempfile.mkdtemp(prefix="flash-card-smoke-"))
    data = folder / "data"
    data.mkdir()
    (data / VOCABULARY_NAME).write_text(words_file_text(words), encoding="utf-8")
    argv = [*command, "--data-dir", str(data), "--level", "all", "--no-speech"]
    program = start(argv)
    try:
        window = _wait_for_window(run, sleep, timeout)
        if window is None:
            return RunResult(False, None, 0, False)
        width, height = parse_geometry(
            run(["xdotool", "getwindowgeometry", "--shell", window])
        )
        x, y = known_button_point(width, height)
        run(["xdotool", "mousemove", "--window", window, str(x), str(y), "click", "1"])
        rows = _wait_for_progress(data / PROGRESS_NAME, sleep)
        return RunResult(True, (x, y), rows, progress_ok(rows, words))
    finally:
        program.stop()
        shutil.rmtree(folder, ignore_errors=True)
 def main(
    argv: Sequence[str] | None = None,
    run: RunCommand = real_run,
    start: StartProgram = real_start,
    sleep: Sleep = time.sleep,
 ) -> int:
    """Run the driver.
    @param argv Command line arguments, or None for `sys.argv`.
    @param run Runs xdotool.
    @param start Starts the program.
    @param sleep Waits between polls.
    @return 0 when every run is ok, otherwise 1.
    """
    parser = argparse.ArgumentParser(description=(__doc__ or "").splitlines()[0])
    parser.add_argument("--repeat", type=int, default=5)
    parser.add_argument("--timeout", type=float, default=30.0)
    parser.add_argument("--words", type=int, default=3)
    parser.add_argument("--command", nargs=argparse.REMAINDER, required=True)
    args = parser.parse_args(argv)
    passed = 0
    for index in range(1, args.repeat + 1):
        began = time.monotonic()
        result = run_once(args.command, args.words, args.timeout, run, start, sleep)
        passed += result.ok
        line = {
            "run": index,
            "window": result.window,
            "clicked": list(result.clicked) if result.clicked else None,
            "progress_rows": result.progress_rows,
            "ok": result.ok,
            "seconds": round(time.monotonic() - began, 2),
        }
        sys.stdout.write(json.dumps(line) + "\n")
    summary = {"runs": args.repeat, "passed": passed}
    sys.stdout.write(json.dumps(summary) + "\n")
    return 0 if passed == args.repeat else 1
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,78 @@
 #!/usr/bin/env bash
 # Start a virtual desktop for the checks. Source this file; it must not be run.
 #
 # Purpose:  give the checks a desktop of their own (a virtual X screen) so that
 #           no window opens on the host (ADR-0005).
 # Usage:    . tools/docker/start-desktop.sh
 # Options:  none
 # Env in:   DISPLAY (default :99), SCREEN_SIZE (default 1280x1024x24),
 #           SHELL_WAIT_SECONDS (seconds to wait for GNOME Shell, default 25)
 # Env out:  DISPLAY, DBUS_SESSION_BUS_ADDRESS, DESKTOP_KIND (gnome-shell or
 #           mutter), DESKTOP_LOG_DIR (logs and the file desktop-kind)
 # Needs:    bash 5, Xvfb, xdpyinfo, xprop, dbus-launch, gnome-shell, mutter
 # Exit:     returns 0 when a desktop runs; 1 when no window manager came up
 #
 # Steps: Xvfb; a private D-Bus session; GNOME Shell first, and GNOME's window
 # manager (mutter) when the shell does not come up in a container (it needs a
 # login manager that a container does not have). The kind that runs is printed.
 export DISPLAY="${DISPLAY:-:99}"
 screen_size="${SCREEN_SIZE:-1280x1024x24}"
 shell_wait_seconds="${SHELL_WAIT_SECONDS:-25}"
 DESKTOP_LOG_DIR="$(mktemp -d)"
 export DESKTOP_LOG_DIR
 trap 'rm -rf "${DESKTOP_LOG_DIR}"' EXIT
 if ! xdpyinfo -display "${DISPLAY}" >/dev/null 2>&1; then
  Xvfb "${DISPLAY}" -screen 0 "${screen_size}" -nolisten tcp >"${DESKTOP_LOG_DIR}/xvfb.log" 2>&1 &
  for _ in $(seq 1 40); do
    xdpyinfo -display "${DISPLAY}" >/dev/null 2>&1 && break
    sleep 0.25
  done
 fi
 if [[ -z "${DBUS_SESSION_BUS_ADDRESS:-}" ]]; then
  eval "$(dbus-launch --sh-syntax)"
  export DBUS_SESSION_BUS_ADDRESS
 fi
 # Name of the window manager that owns the screen, or nothing.
 wm_name() {
  local check
  check="$(xprop -root _NET_SUPPORTING_WM_CHECK 2>/dev/null | awk '{print $NF}')"
  [[ -n "${check}" ]] || return 0
  xprop -id "${check}" _NET_WM_NAME 2>/dev/null | sed -n 's/.*= "\(.*\)"/\1/p'
 }
 DESKTOP_KIND=""
 if command -v gnome-shell >/dev/null 2>&1; then
  gnome-shell --x11 --sm-disable >"${DESKTOP_LOG_DIR}/gnome-shell.log" 2>&1 &
  gnome_pid=$!
  for _ in $(seq 1 $((shell_wait_seconds * 2))); do
    if kill -0 "${gnome_pid}" 2>/dev/null && wm_name | grep -qi "gnome"; then
      DESKTOP_KIND="gnome-shell"
      break
    fi
    sleep 0.5
  done
  if [[ -z "${DESKTOP_KIND}" ]]; then
    kill "${gnome_pid}" 2>/dev/null || true
  fi
 fi
 if [[ -z "${DESKTOP_KIND}" ]]; then
  mutter --x11 --sm-disable >"${DESKTOP_LOG_DIR}/mutter.log" 2>&1 &
  for _ in $(seq 1 40); do
    if wm_name | grep -qi "mutter"; then
      DESKTOP_KIND="mutter"
      break
    fi
    sleep 0.25
  done
 fi
 if [[ -z "${DESKTOP_KIND}" ]]; then
  echo "error: no window manager came up on ${DISPLAY}" >&2
  return 1
 fi
 export DESKTOP_KIND
 echo "${DESKTOP_KIND}" >"${DESKTOP_LOG_DIR}/desktop-kind"
 echo "desktop: ${DESKTOP_KIND} on ${DISPLAY}"
@@ -0,0 +1,36 @@
 <!--
  Windows Sandbox configuration of the flash card smoke test (ADR-0005).
  Do not open this file directly: tools/sandbox/run.ps1 replaces the three
  @...@ placeholders with absolute host paths and starts the sandbox.
  dist     read-only   the built flash-card.exe
  scripts  read-only   smoke.ps1, which runs inside the sandbox
  out      read-write  result.json and screenshots written by smoke.ps1
 -->
 <Configuration>
  <VGpu>Disable</VGpu>
  <Networking>Disable</Networking>
  <AudioInput>Disable</AudioInput>
  <VideoInput>Disable</VideoInput>
  <ClipboardRedirection>Disable</ClipboardRedirection>
  <MappedFolders>
    <MappedFolder>
      <HostFolder>@DIST@</HostFolder>
      <SandboxFolder>C:\fc\dist</SandboxFolder>
      <ReadOnly>true</ReadOnly>
    </MappedFolder>
    <MappedFolder>
      <HostFolder>@SCRIPTS@</HostFolder>
      <SandboxFolder>C:\fc\scripts</SandboxFolder>
      <ReadOnly>true</ReadOnly>
    </MappedFolder>
    <MappedFolder>
      <HostFolder>@OUT@</HostFolder>
      <SandboxFolder>C:\fc\out</SandboxFolder>
      <ReadOnly>false</ReadOnly>
    </MappedFolder>
  </MappedFolders>
  <LogonCommand>
    <Command>powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\fc\scripts\smoke.ps1 -Runs @RUNS@</Command>
  </LogonCommand>
 </Configuration>
@@ -0,0 +1,56 @@
 <#
 .SYNOPSIS
  Start the Windows Sandbox smoke test of dist\flash-card.exe from the host.
 .DESCRIPTION
  Writes a configuration from flash-card.wsb with absolute paths, starts
  Windows Sandbox, waits for out\result.json and prints the summary.
  The tests themselves (window, click, progress file) run inside the sandbox
  with the sandbox's own mouse; the host's mouse and focus are not used.
  Windows Sandbox shows its own window while it runs. Needs Windows 11 Pro
  with the feature "Windows Sandbox" enabled.
 .EXAMPLE
  powershell -File tools\sandbox\run.ps1 -Runs 5
 #>
 param(
    [int]$Runs = 5,
    [int]$TimeoutMinutes = 15
 )
 $ErrorActionPreference = 'Stop'
 $root = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
 $dist = Join-Path $root 'dist'
 $scripts = $PSScriptRoot
 $out = Join-Path $root 'build\sandbox-out'
 if (-not (Test-Path (Join-Path $dist 'flash-card.exe'))) {
    throw "dist\flash-card.exe not found: build it first with python tools\build_executable.py"
 }
 if (-not (Get-Command WindowsSandbox.exe -ErrorAction SilentlyContinue)) {
    throw "WindowsSandbox.exe not found: enable the Windows feature 'Windows Sandbox' (Windows 11 Pro)"
 }
 if (Get-Process -Name 'WindowsSandbox*' -ErrorAction SilentlyContinue) {
    throw "A Windows Sandbox is already running: close it first (only one can run at a time)"
 }
 Remove-Item $out -Recurse -Force -ErrorAction SilentlyContinue
 New-Item -ItemType Directory -Path $out -Force | Out-Null
 $config = (Get-Content (Join-Path $scripts 'flash-card.wsb') -Raw) `
    -replace '@DIST@', $dist -replace '@SCRIPTS@', $scripts -replace '@OUT@', $out -replace '@RUNS@', $Runs
 $wsb = Join-Path $out 'run.wsb'
 Set-Content -Path $wsb -Value $config -Encoding UTF8
 Write-Host "Starting Windows Sandbox ($Runs runs); results in $out"
 Start-Process -FilePath WindowsSandbox.exe -ArgumentList "`"$wsb`""
 $result = Join-Path $out 'result.json'
 $end = (Get-Date).AddMinutes($TimeoutMinutes)
 while ((Get-Date) -lt $end -and -not (Test-Path $result)) { Start-Sleep -Seconds 5 }
 if (-not (Test-Path $result)) { throw "No result.json after $TimeoutMinutes minutes" }
 Start-Sleep -Seconds 3
 $summary = Get-Content $result -Raw | ConvertFrom-Json
 Write-Host ("passed {0} of {1} runs in {2}" -f $summary.passed, $summary.runs, $summary.os)
 $summary.results | Format-Table run, window, clicked, progress_rows, ok, seconds
 if ($summary.passed -ne $summary.runs) { exit 1 }
@@ -0,0 +1,132 @@
 <#
 .SYNOPSIS
  Smoke test of flash-card.exe, run INSIDE Windows Sandbox (ADR-0005).
 .DESCRIPTION
  Starts the executable on the sandbox's own desktop, presses the known button
  with the sandbox's own mouse, reads the progress file, takes screenshots and
  writes result.json to C:\fc\out. Then it shuts the sandbox down.
  It never touches the host: the host sees only the mapped folders.
 #>
 param(
    [int]$Runs = 5,
    [string]$Exe = 'C:\fc\dist\flash-card.exe',
    [string]$Out = 'C:\fc\out'
 )
 $ErrorActionPreference = 'Stop'
 Add-Type -AssemblyName System.Drawing
 Add-Type @'
 using System;
 using System.Text;
 using System.Runtime.InteropServices;
 public static class Win {
    public delegate bool EnumProc(IntPtr h, IntPtr l);
    [DllImport("user32.dll")] public static extern bool EnumWindows(EnumProc p, IntPtr l);
    [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
    [DllImport("user32.dll", CharSet = CharSet.Unicode)] public static extern int GetWindowText(IntPtr h, StringBuilder s, int n);
    [DllImport("user32.dll")] public static extern bool GetClientRect(IntPtr h, out RECT r);
    [DllImport("user32.dll")] public static extern bool ClientToScreen(IntPtr h, ref POINT p);
    [DllImport("user32.dll")] public static extern bool SetCursorPos(int x, int y);
    [DllImport("user32.dll")] public static extern void mouse_event(uint f, uint x, uint y, uint d, UIntPtr e);
    [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);
    [DllImport("shcore.dll")] public static extern int SetProcessDpiAwareness(int v);
    [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
    [StructLayout(LayoutKind.Sequential)] public struct POINT { public int X, Y; }
    public static IntPtr Find(string title) {
        IntPtr found = IntPtr.Zero;
        EnumWindows(delegate (IntPtr h, IntPtr l) {
            if (IsWindowVisible(h)) {
                var sb = new StringBuilder(256);
                GetWindowText(h, sb, 256);
                if (sb.ToString() == title) { found = h; return false; }
            }
            return true;
        }, IntPtr.Zero);
        return found;
    }
 }
 '@
 [void][Win]::SetProcessDpiAwareness(2)
 function Wait-Window([int]$Seconds) {
    $end = (Get-Date).AddSeconds($Seconds)
    while ((Get-Date) -lt $end) {
        $h = [Win]::Find('Flashy')
        if ($h -ne [IntPtr]::Zero) { return $h }
        Start-Sleep -Milliseconds 250
    }
    return [IntPtr]::Zero
 }
 function Save-Screen([string]$Path) {
    $b = [System.Windows.Forms.SystemInformation]::VirtualScreen
    $bmp = New-Object System.Drawing.Bitmap $b.Width, $b.Height
    $g = [System.Drawing.Graphics]::FromImage($bmp)
    $g.CopyFromScreen($b.Left, $b.Top, 0, 0, $bmp.Size)
    $bmp.Save($Path, [System.Drawing.Imaging.ImageFormat]::Png)
    $g.Dispose(); $bmp.Dispose()
 }
 Add-Type -AssemblyName System.Windows.Forms
 $work = Join-Path $env:TEMP 'fc-smoke'
 $results = @()
 for ($n = 1; $n -le $Runs; $n++) {
    $run = [ordered]@{ run = $n; window = $false; clicked = $false; progress_rows = $null; ok = $false; seconds = 0 }
    $t0 = Get-Date
    $dir = Join-Path $work "run$n"
    Remove-Item $dir -Recurse -Force -ErrorAction SilentlyContinue
    New-Item -ItemType Directory -Path (Join-Path $dir 'data') -Force | Out-Null
    Copy-Item $Exe (Join-Path $dir 'flash-card.exe')
    # three words: after one known word the progress file has a header and two cards
    [IO.File]::WriteAllText((Join-Path $dir 'data\ms-da.csv'), "ms;da`naaa;bbb`nccc;ddd`neee;fff`n", (New-Object Text.UTF8Encoding $false))
    $p = Start-Process -FilePath (Join-Path $dir 'flash-card.exe') -ArgumentList '--level', 'all', '--no-speech' -WorkingDirectory $dir -PassThru
    try {
        $h = Wait-Window 60
        if ($h -ne [IntPtr]::Zero) {
            $run.window = $true
            Start-Sleep -Milliseconds 1500
            if ($n -eq 1) { Save-Screen (Join-Path $Out 'sandbox-card.png') }
            $r = New-Object Win+RECT
            [void][Win]::GetClientRect($h, [ref]$r)
            $pt = New-Object Win+POINT
            [void][Win]::ClientToScreen($h, [ref]$pt)
            $x = $pt.X + 650
            $y = $pt.Y + $r.Bottom - 101
            [void][Win]::SetForegroundWindow($h)
            Start-Sleep -Milliseconds 400
            [void][Win]::SetCursorPos($x - 12, $y - 12)
            Start-Sleep -Milliseconds 300
            [void][Win]::SetCursorPos($x, $y)
            Start-Sleep -Milliseconds 400
            [Win]::mouse_event(0x0002, 0, 0, 0, [UIntPtr]::Zero)
            Start-Sleep -Milliseconds 120
            [Win]::mouse_event(0x0004, 0, 0, 0, [UIntPtr]::Zero)
            $run.clicked = $true
            $prog = Join-Path $dir 'data\words_to_learn.csv'
            $end = (Get-Date).AddSeconds(6)
            while ((Get-Date) -lt $end -and -not (Test-Path $prog)) { Start-Sleep -Milliseconds 250 }
            if (Test-Path $prog) {
                $rows = ([IO.File]::ReadAllLines($prog) | Where-Object { $_.Trim() -ne '' }).Count
                $run.progress_rows = $rows
                $run.ok = ($rows -eq 3)
            }
        }
    }
    finally {
        if (-not $p.HasExited) { Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue }
        Get-Process -Name 'flash-card' -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue
    }
    $run.seconds = [math]::Round(((Get-Date) - $t0).TotalSeconds, 1)
    $results += [pscustomobject]$run
    Start-Sleep -Seconds 1
 }
 $summary = [ordered]@{
    runs    = $Runs
    passed  = ($results | Where-Object { $_.ok }).Count
    os      = (Get-CimInstance Win32_OperatingSystem).Caption
    results = $results
 }
 $summary | ConvertTo-Json -Depth 5 | Set-Content -Path (Join-Path $Out 'result.json') -Encoding UTF8
 shutdown.exe /s /t 5
Author	SHA1	Message	Date
Tirsvad	1785dc9635	Resolve pending commit links of the MIL-013 results	2026-10-15 10:10:11 +08:00
Tirsvad	2f192b6936	MIL-013: results of the container and sandbox checks Review record RC-079 (Go-with-conditions): the Debian checks and the Linux smoke tests pass; the Windows Sandbox run is pending because it opens a window on the host. Task: MIL-013#8	2026-10-15 10:10:10 +08:00
Tirsvad	f8ccfca02e	MIL-013: Debian container and Windows Sandbox checks A Debian image (python:3.13-slim-bookworm with Xvfb and GNOME's window manager) runs the linters, the whole test suite, the screenshots and the smoke test of a PyInstaller Linux binary and of the source program, so no window opens on the development machine. The screenshot tool works on Linux, a smoke driver presses the known button with the virtual mouse, and Windows Sandbox scripts are written (not run, they open a window on the host). README and the wiki Install pages describe it. Review records RC-077 (Python) and RC-078 (shell). Task: MIL-013#2 Task: MIL-013#3 Task: MIL-013#4 Task: MIL-013#5 Task: MIL-013#6 Task: MIL-013#7 Task: MIL-013#9 Task: MIL-013#10	2026-10-15 10:09:48 +08:00
Tirsvad	a72ddb9175	Merge pull request 'MIL-013 plan and documents: container and sandbox checks' (#96 ) from plan-mil-013-container into main TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 6s Details	2026-10-15 03:55:36 +02:00
Tirsvad	bc4395df43	Resolve pending commit links of the MIL-013 plan	2026-10-15 09:55:23 +08:00
Tirsvad	f86bc9136e	MIL-013 plan and documents: container and sandbox checks Milestone MIL-013 (Debian container with GNOME, Windows Sandbox for the executable), ADR-0005, BC-001 and PP-001 updated. Review records RC-073 to RC-076, all Go (autonomous mode, not independent). Task: MIL-013#1	2026-10-15 09:55:21 +08:00
Tirsvad	99858fb13b	Merge pull request 'MIL-012 results: release v0.2.0' (#95 ) from mil-012-results into main TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 6s Details	2026-10-15 03:49:23 +02:00
Tirsvad	c1a92ce34f	Resolve pending commit link of RC-072	2026-10-15 09:48:58 +08:00
Tirsvad	5345fd77d4	MIL-012: release v0.2.0 results The tag v0.2.0 and the release page exist (lightweight tag, no executable attached: the host refuses the upload). Review record RC-072 (Go-with-conditions): the executable smoke test is incomplete and the tag is not annotated. Task: MIL-012#5 Task: MIL-012#6 Task: MIL-012#7	2026-10-15 09:48:57 +08:00
Tirsvad	d7ca24dc69	Merge pull request 'MIL-012: version 0.2.0, CHANGELOG and links' (#94 ) from mil-012-version-0-2-0 into main TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 6s Details	2026-10-15 03:39:35 +02:00
Tirsvad	2d94678899	Resolve pending commit link of RC-071	2026-10-15 09:39:25 +08:00
Tirsvad	7c1f1b6423	MIL-012: version 0.2.0, CHANGELOG and links Version 0.2.0 in pyproject.toml, flash_card.__version__ and the Doxyfile with a test that keeps the three equal; CHANGELOG entry for 0.2.0; README and the wiki Install pages link the release pages. The upload limit probe refused a 1 MB file (413), so the executable is not attached. Review record RC-071 (Go). Task: MIL-012#2 Task: MIL-012#3 Task: MIL-012#4 Task: MIL-012#8	2026-10-15 09:39:16 +08:00
Tirsvad	f9ca635a15	Merge pull request 'MIL-012 plan and documents: release v0.2.0' (#85 ) from plan-mil-012-release-0-2-0 into main TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 8s Details	2026-10-15 03:36:10 +02:00