Add game core logic, CSV storage, tests and ADR-0001 (MIL-002)
Task: MIL-002#1 Task: MIL-002#2 Task: MIL-002#3 Task: MIL-002#4 Task: MIL-002#5
This commit is contained in:
@@ -0,0 +1,51 @@
|
||||
# Read the states with the csv module
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | ADR-0001 |
|
||||
| CrossReference | [BC-001], [SA-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-13 | Accepted | Claude (AI) for S01 | AI as stand-in for S01 | Initial version; review RC-008: Go | pending |
|
||||
|
||||
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The lectures read `50_states.csv` with pandas (`pandas.read_csv`, a DataFrame, then `DataFrame.to_csv` for `states_to_learn.csv`). The file has 50 rows and three columns (`state`, `x`, `y`). [BC-001] sets the constraint "avoid adding runtime dependencies unless they are needed", and [SA-001] records that S03 wants no runtime dependencies while S02 wants the assignment's function and variable names.
|
||||
|
||||
Options evaluated:
|
||||
|
||||
1. **pandas**: matches the lectures literally; adds a large runtime dependency (with NumPy) for 50 rows and makes installation and CI slower.
|
||||
2. **Standard library `csv` module**: no dependency; a few more lines to read and write; the assignment's names (`data`, `states`, `guessed_states`, `missing_states`) can be kept.
|
||||
|
||||
## Decision
|
||||
|
||||
Read and write the CSV files with the standard library `csv` module, and keep the assignment's names for variables and functions. pandas is not a runtime dependency.
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
|
||||
- The game has no runtime dependencies, so S03 installs nothing and CI is fast.
|
||||
- The game logic is plain functions over `str` and `int`, easy to test without a display.
|
||||
|
||||
**Negative:**
|
||||
|
||||
- The code differs from the lecture's pandas calls, so S02 compares by names and behaviour, not by line.
|
||||
- Reading and writing the CSV takes a few more lines than `read_csv` and `to_csv`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- [BC-001] - Success criterion 6 (no runtime dependency beyond the standard library) is met without exception.
|
||||
- [SA-001] - Resolves the S02 and S03 conflict in favour of no runtime dependency.
|
||||
|
||||
---
|
||||
|
||||
[BC-001]: ../business-case.md
|
||||
[SA-001]: ../stakeholder-analysis.md
|
||||
@@ -15,8 +15,8 @@ document of a type. `Primary File` may contain a glob (e.g.
|
||||
| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
|
||||
| PP | Project Plan | docs/project-plan.md | 002 |
|
||||
| MIL | Milestone / Gateway | docs/milestones/*.md | 005 |
|
||||
| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0001 |
|
||||
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 008 |
|
||||
| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0002 |
|
||||
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 010 |
|
||||
|
||||
## Languages
|
||||
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# SQA Review Record
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | RC-008 |
|
||||
| CrossReference | [QC-ADR-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-13 | Proposed | Claude (AI) for S01 | AI as stand-in for S01 | Initial review record: Go | pending |
|
||||
|
||||
---
|
||||
|
||||
## Artifact Under Review
|
||||
|
||||
- Instance reviewed: [ADR-0001]
|
||||
- Checklist used: [QC-ADR-001]
|
||||
- Scope: full review
|
||||
- Language and domain: n/a (technical type)
|
||||
- Language reviewer: none
|
||||
- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the author is the same AI)
|
||||
|
||||
## Checklist Results
|
||||
|
||||
### QC-ADR-001
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential (Mandatory) | Pass | ID ADR-0001 matches file adr-0001-...; first ADR. |
|
||||
| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated (Mandatory) | Pass | Context states problem, constraints from BC-001 and SA-001, and two options. |
|
||||
| 3 | At least two options were considered, or the absence of alternatives is justified (Mandatory) | Pass | Two options: pandas and the csv module. |
|
||||
| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options (Mandatory) | Pass | Decision is two unhedged sentences and equals option 2. |
|
||||
| 5 | Consequences list both Positive and Negative outcomes (Mandatory) | Pass | Positive and Negative lists present. |
|
||||
| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them (Optional) | Pass | Portability and installation effect named (no runtime dependency). |
|
||||
| 7 | Affected Artifacts are listed as links, and each is also in CrossReference (Mandatory) | Pass | BC-001 and SA-001 are linked 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 (Mandatory) | Pass | One Version History row; to be set Accepted on this Go. |
|
||||
| 9 | A superseded or deprecated ADR names its successor, and the successor links back (Optional) | N-A | Not superseded or deprecated. |
|
||||
| 10 | Written in business or technical language of the domain, with no unexplained abbreviations (Optional) | Pass | Abbreviations spelled out or defined (CSV file name, CI named as continuous integration in BC-001). |
|
||||
| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these (Mandatory) | Pass | Status values are from the allowed list. |
|
||||
|
||||
## Overall Verdict
|
||||
|
||||
Go - ADR-0001 meets every Mandatory criterion.
|
||||
|
||||
## Action Items
|
||||
|
||||
| Action | Owner | Due |
|
||||
| --- | --- | --- |
|
||||
| None | S01 | |
|
||||
|
||||
---
|
||||
|
||||
[QC-ADR-001]: ../../../framework/qc/artifacts/qc-adr.md
|
||||
|
||||
[ADR-0001]: ../../adr/adr-0001-csv-module-over-pandas.md
|
||||
@@ -0,0 +1,60 @@
|
||||
# SQA Review Record
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | RC-009 |
|
||||
| CrossReference | [QC-PY-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-13 | Proposed | Claude (AI) for S01 | AI as stand-in for S01 | Initial review record: Go | pending |
|
||||
|
||||
---
|
||||
|
||||
## Artifact Under Review
|
||||
|
||||
- Instance reviewed: source and tests delivered by MIL-002 (branch mil-002-game-core)
|
||||
- Checklist used: [QC-PY-001]
|
||||
- Scope: full review
|
||||
- Language and domain: n/a (technical type)
|
||||
- Language reviewer: none
|
||||
- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the author is the same AI)
|
||||
|
||||
## Checklist Results
|
||||
|
||||
### QC-PY-001
|
||||
|
||||
| # | Criterion | Status | Evidence/Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) (Mandatory) | Pass | snake_case functions, PascalCase State; ruff N rules pass. |
|
||||
| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes (Mandatory) | Pass | find_state, get_missing_states, save_states_to_learn state purpose; assignment names kept. |
|
||||
| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions (Mandatory) | Pass | ruff format and check clean, no suppressions. |
|
||||
| 4 | Every function and method signature is type-annotated, including `-> None` (Mandatory) | Pass | All signatures annotated; mypy --strict passes. |
|
||||
| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) (Mandatory) | N-A | No exception handling; a missing file raises FileNotFoundError to the caller. |
|
||||
| 6 | No mutable default arguments and no shadowed builtins (Mandatory) | Pass | Default arguments are immutable (Path values); no builtin shadowed. |
|
||||
| 7 | Files, locks and connections are managed with context managers (Mandatory) | Pass | storage.py opens files with `with`. |
|
||||
| 8 | Public modules, classes and functions have docstrings that say what, not how (Optional) | Pass | Docstrings with Doxygen @param/@return on all public items. |
|
||||
| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output (Mandatory) | Pass | No print and no logging in the logic. |
|
||||
| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded (Mandatory) | N-A | No Design Class Diagram exists; State is a plain value object. |
|
||||
| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network (Mandatory) | Pass | 15 tests named for behaviour, tmp_path for files, no network or order dependence. |
|
||||
| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment (Optional) | Pass | mypy strict reports no issues. |
|
||||
| 13 | Dependencies are declared and pinned in the project's dependency file, none unused (Optional) | Pass | No runtime dependencies (ADR-0001). |
|
||||
| 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 (Mandatory) | Pass | Column names and paths defined once in constants.py; matching rule in find_state only. |
|
||||
| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles (Mandatory) | Pass | states.py imports no IO or UI; storage.py imports inward (states, constants); no cycles. |
|
||||
| 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 (Mandatory) | Pass | states.py has one reason to change (rules), storage.py another (file format); no inheritance. |
|
||||
|
||||
## Overall Verdict
|
||||
|
||||
Go - Mandatory criteria pass for states.py, storage.py and their tests (ruff, mypy --strict, 17 pytest tests, doxygen without warnings).
|
||||
|
||||
## Action Items
|
||||
|
||||
| Action | Owner | Due |
|
||||
| --- | --- | --- |
|
||||
| None | S01 | |
|
||||
|
||||
---
|
||||
|
||||
[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
|
||||
Reference in New Issue
Block a user