024-snake/docs/milestones/mil-004-high-score-file.md

MIL-004: High score file

Metadata

Key	Value
ID	MIL-004
CrossReference	BC-001
Language	en
Domain	it

Version History

Date	Status	Author	Reviewer	Change	Commit
2026-10-13	Accepted	Jens Tirsvad Nielsen	AI as stand-in for S01	Initial version, reviewed in RC-007 (Go)	e004c34

---

Purpose

This gate decides whether the high score survives between games: it is read from data.txt with with open(...) when the scoreboard is made, converted from text to an integer, and written back to the file when a new high score is reached. It also decides the behaviour where the lecture is silent: a missing, empty or damaged file. The work is delivered on the branch mil-004-high-score-file and one pull request.

Deliverable

Changed src/snake_game/scoreboard.py and constants.py, functions that read and write the high score, and tests that use a temporary file. The game, started again after a new high score, shows that high score.

Go / No-Go Criteria

#	Criterion (objectively checkable)	Go	No-Go
1	The high score is read at the start	Scoreboard() reads the file named by the constant HIGH_SCORE_FILE (data.txt) with a with statement, converts the text with int and shows the value as High Score	The value is not read, the file is opened without with, or the text is not converted
2	A new high score is written	When reset finds a score above the high score, the file holds the new value as text; a lower or equal score does not write the file	The file is not written, is written for a lower score, or holds something other than the number
3	A missing file is created	Starting without data.txt shows High Score: 0 and leaves a data.txt that holds 0	A traceback, or no file
4	A damaged file reads as 0	An empty file, a file with text that is not a whole number and a negative number all give a high score of 0 without a traceback	A traceback, or a negative high score
5	The path is a parameter	The file name is a constant used as the default of a parameter, and every test passes a temporary path	A test uses the real data.txt
6	The high score survives a restart	S01 reaches a new high score, closes the window, starts python -m snake_game again and sees the same high score	The value is lost
7	data.txt is not tracked	git check-ignore data.txt lists it and no data.txt is in the change	The file is tracked
8	Tests, lint, format and types are clean	pytest, python -m ruff check src tests, python -m ruff format --check src tests and python -m mypy exit 0, as in continuous integration (CI); no test opens a window	Any of them fails
9	doxygen Doxyfile builds	0 warnings	Any warning
10	The code is reviewed	RC-* against QC-PY-001 has the verdict Go	Verdict No-Go or Go-with-conditions
11	No secret is in the change	.env is not tracked and no token appears in any changed file	A token is found in the diff

Dependencies

Depends on	Reason
MIL-003 accepted and merged	Scoreboard.reset and the two scores exist there

Traceability

Business Case objective / KPI / user story	Reference
Objective 5: the file read and written with with	BC-001, criterion 4 in Success Criteria
Objective 6: a missing or damaged file	BC-001, criterion 5 in Success Criteria
Objective 9: tests never touch the real file	BC-001, criterion 6 in Success Criteria

Ownership

Role	Stakeholder ID (SA)
Owner	S01
Approving reviewer	S01

Target Date

2026-10-21 — fourth of five gateways.

Tasks

#	Task	Summary	Needs its own Use Case/User Story?	Reference
1	Add the high score file constant	Add HIGH_SCORE_FILE: Final[str] = "data.txt" to constants.py with a Doxygen comment, and a test of it.	No
2	Read the high score from the file	Add a function that opens the file with with open(path) as data, reads it, converts the text with int and returns it; Scoreboard.__init__ takes the path as a parameter with the constant as default and sets high_score from it. Tests with a temporary file.	No
3	Write the high score to the file	In Scoreboard.reset, when a new high score is reached, open the file with with open(path, mode="w") as data and write the number as text. Tests check the file content after a higher, equal and lower score.	No
4	Handle a missing or damaged file	A missing file is created holding 0; an empty file, text that is not a whole number or a negative number read as 0 (objective 6 of the Business Case). Tests for each case.	No
5	Keep the tests away from the real data.txt	Every test that makes a Scoreboard passes a pytest tmp_path file; a guard in tests/conftest.py fails a test that would open the default path.	No
6	Document the high score file in the README	Describe in the Run section where data.txt is, that it is created at the first start, how to reset the high score (delete the file) and that it is not tracked by git. Serves S02.	No
7	Verify the high score file end to end	Run pytest, ruff check, ruff format --check, mypy and doxygen Doxyfile in a fresh .venv, reach a high score, restart the game, delete and damage data.txt and start again, and record the results in the pull request.	No

---