Evidence: Block 1 · Foundational (block-1)

• block type: block
• date: 2026-08-15
• resulting state: closed/verified
• story points (combined assembled cost): 11649
• execution id: 20260815.171742.357Z-0c435543

Stories built

• Establish the Flask application architecture and module boundaries. (architecture) [story]

Reusable compacts

• ARCHITECTURE_compact.md

Stacked context

• compass: COMPASS.md (SP 724)
• implements: ARCHITECTURE.md (SP 970)
• stack: python.md (SP 3892)
• stack: flask.md (SP 4232)
• stack: sqlite.md (SP 1763)

Build directory changes

• .env.example
• .gitignore
• app/init.py
• app/persistence.py
• app/routes.py
• app/static/css/style.css
• app/templates/base.html
• app/templates/index.html
• bin/test.sh
• config.py
• pyproject.toml
• pytest.ini
• run.py
• tests/conftest.py
• tests/test_architecture.py
• tests/test_routes.py
• uv.lock

Pre-build acceptance observation

• RED: architecture-factory (ARCHITECTURE.md)

intent: The application factory creates a runnable Flask application with an HTTP test client. return code: 1 stderr: Traceback (most recent call last): File "architecture-factory.py", line 1, in <module> from app import create_app
ModuleNotFoundError: No module named 'app'

• RED: architecture-isolation (ARCHITECTURE.md)

intent: Separate application instances can be created independently for isolated execution. return code: 1 stderr: Traceback (most recent call last): File "architecture-isolation.py", line 1, in <module> from app import create_app
ModuleNotFoundError: No module named 'app'

• RED: architecture-entrypoint (ARCHITECTURE.md)

intent: The web entrypoint exposes the application factory without requiring a development server to start during import. return code: 1 stderr: Traceback (most recent call last): File "architecture-entrypoint.py", line 3, in <module> module = importlib.import_module("app") ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/barlo/.local/share/uv/python/cpython-3.12.13-linux-x86_64-gnu/lib/python3.12/importlib/init.py", line 90, in import_module return _bootstrap._gcd_import(name[level:], package, level) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "<frozen importlib._bootstrap>", line 1387, in _gcd_import File "<frozen importlib._bootstrap>", line 1360, in _find_and_load File "<frozen importlib._bootstrap>", line 1324, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'app'

Post-build programmatic acceptance

• PASS: architecture-factory (ARCHITECTURE.md)

intent: The application factory creates a runnable Flask application with an HTTP test client. target interpreter: /mnt/c/Users/barlo/projects/drydock/uat/ReadingList/runs/20260815.171255/build/ReadingList/.venv/bin/python provisioning: not required return code: 0

• PASS: architecture-isolation (ARCHITECTURE.md)

intent: Separate application instances can be created independently for isolated execution. target interpreter: /mnt/c/Users/barlo/projects/drydock/uat/ReadingList/runs/20260815.171255/build/ReadingList/.venv/bin/python provisioning: not required return code: 0

• PASS: architecture-entrypoint (ARCHITECTURE.md)

intent: The web entrypoint exposes the application factory without requiring a development server to start during import. target interpreter: /mnt/c/Users/barlo/projects/drydock/uat/ReadingList/runs/20260815.171255/build/ReadingList/.venv/bin/python provisioning: not required return code: 0

Build summary

<reusable-compact filename="ARCHITECTURE.md">
Flask app factory: from app import create_app; supports isolated overrides including TESTING and DATABASE. HTTP routes live in app.routes; SQLite access is confined to typed app.persistence; templates/static assets live under app/; tests use pytest; bin/test.sh runs the complete suite. Root / must return 200, and independent app instances must not share state. </reusable-compact>

RESULT: SUCCESS

FILES CHANGED:

• .env.example
• .gitignore
• app/init.py
• app/persistence.py
• app/routes.py
• app/templates/base.html
• app/templates/index.html
• app/static/css/style.css
• bin/test.sh
• config.py
• pyproject.toml
• pytest.ini
• run.py
• tests/conftest.py
• tests/test_architecture.py
• tests/test_routes.py
• uv.lock

SUMMARY: Implemented the Flask application factory, isolated SQLite persistence boundary, route registration, templates, configuration, tests, and POSIX test launcher. sh bin/test.sh passes all 5 tests; Ruff also passes.

BLOCKERS:

• None