Unify documentation rules across languages and fix the Python template

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Python/DESIGN_DOCUMENT.md

@@ -19,13 +19,13 @@
 
 All detailed documentation of features and systems belongs in the `docs/` folder, not in the project root.
 
-The root directory contains only the core documents: `DESIGN_DOCUMENT.md`, `AGENTS.md`, `PROJECT.md`, `CHANGELOG.md`.
+The root directory contains only the core documents: `README.md`, `AGENTS.md`, `DESIGN_DOCUMENT.md`, `PROJECT.md`, `CHANGELOG.md`.
 
 ---
 
 ## 1. Code Style
 
-- **PEP8** with 150-character lines (Ruff)
+- **PEP8** with 120-character lines (Ruff)
 - **4 spaces** indentation
 - **snake_case** functions/variables, **PascalCase** classes, **SCREAMING_SNAKE_CASE** constants
 - **Type hints** required on all functions
@@ -76,7 +76,7 @@ Use **loguru** for all internal logging. Never log secrets, passwords, tokens, o
 
 File sink retains **max 10 log files** (`retention=10`). No rotation by size — each run creates a new file via `{time}` in the filename.
 
-The `DEBUG` sink is only active when `constants.DEBUG` is `True` (controlled by `ENV_DEBUG=true` in `.env`).
+The `DEBUG` sink is only active when `constants.DEFAULT_DEBUG` is `True` (controlled by `ENV_DEBUG=true` in `.env`).
 
 Additional sinks (e.g. GUI log panels) may be added per project as needed.
 
@@ -131,6 +131,7 @@ Run before every commit:
 ```bash
 poetry run ruff check
 poetry run mypy
+poetry run pytest
 ```
 
 ---
@@ -147,6 +148,10 @@ poetry run <cmd>                  # Run command in virtualenv
 
 Never edit `pyproject.toml` directly to add or remove dependencies.
 
+### poetry.lock
+
+`poetry.lock` **is committed** for applications — it pins the exact dependency graph and keeps builds reproducible.
+
 ---
 
 ## 12. Project Structure
@@ -171,12 +176,24 @@ When a project is distributed as a standalone executable (no Python required on
 
 - Use **PyInstaller** to compile each entry point into a single `.exe`
 - Each tool has its own `.spec` file in the project root
-- All console tools must use `console=True` in the `.spec` — tools rely on `input()` and `print()` for user interaction
+- **Console tools use `console=True`** in the `.spec` — they rely on `input()` and `print()` for user interaction. GUI applications turn the console off with `ENV_BUILD_CONSOLE=false`; that flag is independent of `ENV_DEBUG`
 - Compiled executables are stored in `dist/` and **committed to the repository** — the repository serves as the distribution channel for internal teams
 - `.gitignore` must **not** exclude `dist/` in projects that use this deployment model
 
-Build command:
+### prebuild.py
+
+`prebuild.py` runs before PyInstaller. It verifies that the active interpreter is the project `.venv`, prints the resolved version, and rewrites the `console=` line in the `.spec` to match `.env`.
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `ENV_BUILD_CONSOLE` | `true` | Value written into `console=` in the `.spec` |
+| `ENV_BUILD_SPEC` | `<project folder>.spec` | Which `.spec` file to update |
+
+`prebuild.py` touches one `.spec` per run — with several entry points, set `ENV_BUILD_SPEC` for each build.
+
+Build commands:
 ```bash
+poetry run python prebuild.py
 poetry run pyinstaller ToolName.spec
 ```
 
@@ -200,13 +217,16 @@ poetry run pyinstaller ToolName.spec
 
 ### Task notation
 
-Tasks are written as single-line comments directly in code, or in `PROJECT.md` for cross-cutting concerns:
+Tasks are written as single-line comments directly in code, using the **Todo Tree** tags defined in `AGENTS.md` (`TODO`, `FIXME`, `BUG`, `HACK`, `NOTE`). `PROJECT.md` carries only cross-cutting tasks that have no single place in the code.
 
 ```python
-# TODO: one-liner description of a task to be done
-# FIXME: one-liner description of a known bug to be fixed
+# TODO: extract this into a separate loader
+# FIXME: crashes on an empty file
+# BUG: rounding is off by one cent on negative amounts
+# HACK: temporary workaround until the API adds paging
+# NOTE: order matters here, the parser is stateful
 ```
 
-No other task format is used — no checkboxes, no numbered lists in documentation.
+No other task format is used — **no checkboxes, no numbered lists in documentation**.
 
-If a `# TODO:` comment already exists at a specific location in code, do not repeat it in `PROJECT.md`.
+If a tag already exists at a specific location in code, do not repeat it in `PROJECT.md`.