@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/core/shared/skills/do-code-review/languages/dart.md

@@ -0,0 +1,108 @@
+---
+language: dart
+extensions: [".dart"]
+---
+
+# Dart / Flutter — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Dart and Flutter-specific rules and idioms.
+
+---
+
+## PR Analyzer — Dart / Flutter Risk Signals
+
+- `print()` statements left in production code — use a logging package
+- `// ignore:` lint suppression comments — verify they are justified
+- `!` null assertion operator used broadly without justification
+- Hardcoded API keys, tokens, or URLs in Dart source — use environment variables or a secrets package
+- `TODO` / `FIXME` near widget lifecycle or state management code
+
+---
+
+## Code Quality — Dart Checks
+
+- `dynamic` used where a concrete type is known — defeats static analysis
+- `!` (null assertion) used broadly — prefer null-safe patterns
+- `StatefulWidget` used where `StatelessWidget` suffices — prefer stateless
+- `setState` called with heavy computation inside — offload before calling
+- `BuildContext` used across async gaps without checking `mounted`
+- Missing `const` constructor on widgets that could be constant
+
+---
+
+## Security
+
+- Flag API keys or secrets hardcoded in Dart source or `pubspec.yaml` — use `--dart-define` or a secrets manager
+- Flag `http` package used without certificate validation disabled intentionally
+- Flag `SharedPreferences` used to store sensitive data — use `flutter_secure_storage`
+- Flag user-controlled input used in `dart:io` file path operations without sanitization
+- Flag `WebView` loading arbitrary user-supplied URLs without validation
+- Flag deep link / URL scheme handlers that don't validate the incoming URL before acting on it
+
+---
+
+## Async / Concurrency
+
+- Flag `BuildContext` used after an `await` without checking `if (!mounted) return` — context may be invalid
+- Flag `Future` returned but not `await`-ed and without `.catchError()` or `unawaited()` — floating future
+- Flag `Isolate.spawn` without a clear message-passing protocol
+- Flag heavy computation on the main isolate — offload with `compute()` or `Isolate.run()`
+- Flag `StreamController` not closed when the owning widget is disposed — memory leak
+- Flag `async*` / `yield*` generators with no error handling on the stream consumer side
+
+---
+
+## Resource Management
+
+- Flag `StreamController` not closed in `dispose()`
+- Flag `AnimationController` not disposed in `dispose()`
+- Flag `TextEditingController` / `FocusNode` / `ScrollController` not disposed in `dispose()`
+- Flag `Timer` not cancelled in `dispose()`
+- Flag listeners added to `ChangeNotifier` / `ValueNotifier` without a corresponding `removeListener`
+
+---
+
+## Exception Handling
+
+- Flag empty `catch` blocks — swallowed errors
+- Flag `catchError` with no handler body — silent failure
+- Flag `Future.error` not surfaced to the UI — show an error state
+- Flag `FlutterError.onError` overridden without calling the original handler
+- Prefer typed `on ExceptionType catch (e)` over generic `catch (e)` where the exception type is known
+
+---
+
+## Performance
+
+- Flag `setState` called for changes that only affect a small subtree — use `ValueNotifier` / `provider` / `Riverpod` to scope rebuilds
+- Flag expensive computation inside `build()` — move to `initState`, a controller, or a `FutureBuilder`
+- Flag `ListView` without `ListView.builder` for long or infinite lists — builds all children at once
+- Flag missing `const` on widgets that never change — prevents unnecessary rebuilds
+- Flag `Image.network` without a caching package in a list — re-downloads on every scroll
+- Flag `RepaintBoundary` missing around frequently-repainted widgets (animations, counters)
+
+---
+
+## Idioms and Best Practices
+
+### Null Safety
+- Prefer `?.` safe navigation and `??` null coalescing over `!` assertions
+- Use `late` only when initialization is guaranteed before first access — document why
+- Prefer early returns over deeply nested null checks
+
+### Flutter Widget Patterns
+- Prefer `StatelessWidget` + external state management over `StatefulWidget` for business logic
+- Keep `build()` methods pure — no side effects, no heavy computation
+- Extract repeated widget subtrees into named widget classes, not just methods, for better rebuild granularity
+- Use `const` constructors wherever possible — compile-time constant widgets skip rebuilds entirely
+
+### State Management
+- Do not mix multiple state management approaches in the same feature
+- Flag business logic inside `build()` — it belongs in a ViewModel, Notifier, or BLoC
+- Prefer `Riverpod` / `provider` / `BLoC` over raw `setState` for anything beyond local UI state
+
+### Modern Dart (3.x)
+- Prefer `sealed` classes for exhaustive pattern matching on domain types
+- Use records (`(int, String)`) for lightweight multi-value returns instead of ad hoc classes
+- Use `switch` expressions with pattern matching instead of long `if/else` chains
+- Prefer `final` for local variables — immutability by default

package/core/shared/skills/do-code-review/languages/go.md

@@ -0,0 +1,92 @@
+---
+language: go
+extensions: [".go"]
+---
+
+# Go — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Go-specific rules and idioms.
+
+---
+
+## PR Analyzer — Go Risk Signals
+
+- `fmt.Println` / `log.Println` debug statements left in production code
+- `//nolint` comments — verify they are justified
+- `unsafe` package imports — require explicit sign-off
+- Hardcoded credentials or tokens in source
+
+---
+
+## Code Quality — Go Checks
+
+- Errors returned but not checked (`_ = someFunc()`)
+- `panic()` used outside of package initialization
+- Goroutines started without a clear lifetime or cancellation path
+- `interface{}` / `any` used where a concrete type or typed interface would work
+- Missing context propagation (`context.Context` not threaded through call chains)
+
+---
+
+## Security
+
+- Flag `database/sql` queries built with `fmt.Sprintf` — require `?` / `$N` placeholders
+- Flag `os/exec` calls with user-controlled arguments without sanitization
+- Flag `html/template` bypassed in favor of `text/template` for HTML output
+- Flag `http.ListenAndServeTLS` with `InsecureSkipVerify: true`
+
+---
+
+## Async / Concurrency
+
+- Flag goroutines started with no clear lifetime or cancellation path — always pass `context.Context`
+- Flag goroutines that write to a channel with no receiver and no `select` default — causes a leak
+- Flag `time.Sleep()` used inside a goroutine as a synchronization mechanism
+- Flag `sync.WaitGroup.Add()` called inside the goroutine it tracks — race condition
+- Flag `sync.Mutex` copied by value — must always be used as a pointer or embedded in a struct
+
+---
+
+## Resource Management
+
+- Flag `http.Response.Body` not closed after reading — even on error paths (`defer resp.Body.Close()`)
+- Flag `os.File` not closed — use `defer f.Close()` immediately after opening
+- Flag `rows.Close()` missing after `sql.Query()` — leaks the DB connection
+- Flag `context.WithCancel` / `context.WithTimeout` cancel function not called — context and resources leak
+
+---
+
+## Exception Handling
+
+- Flag errors assigned to `_` without a comment explaining why it is safe to ignore
+- Flag errors not wrapped with `fmt.Errorf("...: %w", err)` — loses stack context
+- Flag `errors.New` / `fmt.Errorf` strings starting with a capital letter or ending in punctuation — violates Go conventions
+- Flag `panic()` used for expected runtime errors — reserve for programming errors and unrecoverable states
+- Flag `recover()` used to silently swallow panics without logging
+
+---
+
+## Performance
+
+- Flag `fmt.Sprintf` used for simple string concatenation — use `strings.Builder` or `+` for small cases
+- Flag `append()` in a tight loop without pre-allocating slice capacity — use `make([]T, 0, n)`
+- Flag `json.Marshal` / `json.Unmarshal` on large structs in hot paths — consider `json.Encoder` / streaming
+- Flag goroutines spawned per-request without a worker pool for CPU-bound tasks
+
+---
+
+## Idioms and Best Practices
+
+### Error Handling
+- All returned errors must be checked — never assign to `_` without a comment
+- Prefer wrapping with `fmt.Errorf("...: %w", err)` for stack context
+- Use `errors.Is` / `errors.As` for error inspection — never string comparison
+
+### Concurrency
+- Every goroutine must have an owner responsible for its lifetime
+- Always pass `context.Context` as the first argument to functions that do I/O or block
+- Prefer `sync.WaitGroup` or `errgroup` over ad-hoc channel coordination
+
+### Modern Go (1.18+)
+- Prefer generics over `interface{}` for container types and utility functions
+- Use `any` (alias for `interface{}`) in new code for readability

package/core/shared/skills/do-code-review/languages/java.md

@@ -0,0 +1,103 @@
+---
+language: java
+extensions: [".java"]
+---
+
+# Java — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Java-specific rules and idioms.
+
+---
+
+## PR Analyzer — Java Risk Signals
+
+- `System.out.println` / `e.printStackTrace()` left in production code
+- `@SuppressWarnings` annotations — verify they are justified
+- Hardcoded JDBC URLs or credentials in source
+- Raw type usage (`List`, `Map` without generics)
+
+---
+
+## Code Quality — Java Checks
+
+- Empty `catch` blocks swallowing exceptions silently
+- Checked exceptions caught and not re-thrown with context
+- `Closeable` / `AutoCloseable` resources not in try-with-resources
+- Raw type usage — defeats generics type safety
+- Missing `@Override` on overriding methods
+- `InterruptedException` caught without calling `Thread.currentThread().interrupt()`
+
+---
+
+## Security
+
+- Flag JPQL / HQL or native SQL string concatenation — require named parameters or `CriteriaBuilder`
+- Flag `@RequestMapping` without explicit HTTP method restriction on state-changing endpoints
+- Flag user-controlled input passed to `Runtime.exec()` or `ProcessBuilder` without validation
+- Flag `ObjectInputStream.readObject()` on untrusted data — unsafe deserialization
+- Flag hardcoded JDBC URLs or credentials — require environment variables or a vault
+
+---
+
+## Async / Concurrency
+
+- Flag `ExecutorService.submit()` return value ignored — exceptions are swallowed
+- Flag `Thread.sleep()` used as a synchronization mechanism — use `CountDownLatch`, `CompletableFuture`, or `await()`
+- Flag `CompletableFuture` chains with no `.exceptionally()` or `.handle()` terminal handler
+- Flag `InterruptedException` caught without calling `Thread.currentThread().interrupt()`
+- Flag `synchronized` on a non-final field — the lock object can be replaced
+- Flag `HashMap` used in multi-threaded context — use `ConcurrentHashMap`
+
+---
+
+## Resource Management
+
+- Flag `InputStream`, `OutputStream`, `Connection`, `ResultSet`, `PreparedStatement` not wrapped in try-with-resources
+- Flag manual `finally { resource.close() }` — replace with try-with-resources
+- Flag `HttpURLConnection` not disconnected after use
+- Flag JDBC `Connection` obtained from a pool and not returned (missing `close()`) on all paths
+- Flag `static` `HttpClient` or `Connection` fields shared across threads without connection pool management
+
+---
+
+## Exception Handling
+
+- Flag empty `catch` blocks — `catch (Exception e) {}`
+- Flag `InterruptedException` caught without `Thread.currentThread().interrupt()` — breaks cooperative cancellation
+- Flag checked exceptions swallowed in a `catch` and not re-thrown or logged with context
+- Flag `throw new RuntimeException(e)` without a descriptive message — loses context
+- Flag `printStackTrace()` as the sole error handling — use a proper logger
+
+---
+
+## Performance
+
+- Flag `String` concatenation in loops — use `StringBuilder`
+- Flag `List.contains()` / `Map.get()` in a loop on large collections — review data structure choice
+- Flag N+1 JPA / Hibernate queries — use `JOIN FETCH` or `@BatchSize`
+- Flag `new ObjectMapper()` / `new Gson()` instantiated per-request — share a singleton
+- Flag `ResultSet` fully iterated when only the first result is needed — use `LIMIT 1` in the query
+
+---
+
+## Idioms and Best Practices
+
+### Null Safety
+- Prefer returning `Optional<T>` over `null` from methods
+- Flag unchecked dereferences without a prior null guard
+- Do not catch `NullPointerException` — fix the root cause instead
+
+### Collections and Streams
+- Flag `==` used to compare `String` or boxed types — use `.equals()`
+- Flag `.collect(Collectors.toList())` where `.toList()` (Java 16+) suffices
+- Flag premature `.stream().collect()` round-trips that could be a single-pass operation
+
+### Generics
+- Flag raw types in any new code — always parameterize (`List<String>`, not `List`)
+- Flag unchecked cast warnings suppressed without explanation
+
+### Modern Java (11+)
+- Prefer `var` for local variables where the type is obvious from the right-hand side
+- Prefer records for pure data carriers over manual POJOs with getters/setters
+- Prefer `instanceof` pattern matching (`if (obj instanceof String s)`) over explicit casts
+- Prefer `switch` expressions over `switch` statements where a value is returned

package/core/shared/skills/do-code-review/languages/kotlin.md

@@ -0,0 +1,88 @@
+---
+language: kotlin
+extensions: [".kt", ".kts"]
+---
+
+# Kotlin — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Kotlin-specific rules and idioms.
+
+---
+
+## PR Analyzer — Kotlin Risk Signals
+
+- `println()` statements left in production code
+- `@Suppress` annotations — verify they are justified
+- `!!` (not-null assertion) used broadly without justification
+- Hardcoded credentials or API keys in source
+
+---
+
+## Code Quality — Kotlin Checks
+
+- `!!` used broadly — prefer `?.let`, `?:`, or `requireNotNull()`
+- `lateinit var` accessed before initialization
+- Coroutines launched with `GlobalScope` — prefer scoped coroutines
+- `runBlocking` used outside of tests or top-level entry points
+
+---
+
+## Security
+
+- Flag Room / SQLite queries built with string concatenation — require parameterized queries
+- Flag `WebView.loadUrl()` with user-controlled input without validation
+- Flag credentials stored in `SharedPreferences` — require `EncryptedSharedPreferences` or Keychain
+
+---
+
+## Async / Coroutines
+
+- Flag `GlobalScope.launch` / `GlobalScope.async` in production code — use a structured scope
+- Flag `runBlocking` outside of tests or top-level main functions
+- Flag `launch` / `async` without a `CoroutineExceptionHandler` or `supervisorScope` where individual failures should not cancel siblings
+- Flag `Dispatchers.Main` used for CPU-bound work — use `Dispatchers.Default`
+- Flag coroutine cancellation not respected — long loops should check `isActive` or call `yield()`
+
+---
+
+## Resource Management
+
+- Flag `Closeable` / `AutoCloseable` not wrapped in `.use { }` (Kotlin's try-with-resources equivalent)
+- Flag `OkHttpClient` / `Retrofit` instantiated per-request — share a singleton
+- Flag `BroadcastReceiver` registered without a corresponding `unregisterReceiver` — memory / battery leak
+- Flag coroutines that hold a resource across a `suspend` point without structured cleanup in `finally`
+
+---
+
+## Exception Handling
+
+- Flag `runCatching { }.getOrNull()` used broadly — silently swallows all exceptions
+- Flag `catch (e: Exception)` in coroutines without re-throwing `CancellationException` — breaks structured concurrency
+- Flag empty `catch` blocks
+- Flag `throw RuntimeException(e)` without a descriptive message
+- Prefer typed `sealed class` error hierarchies over raw exceptions for domain errors in coroutine flows
+
+---
+
+## Performance
+
+- Flag `buildString` / `StringBuilder` not used for multi-step string construction in loops
+- Flag `List` used for frequent `contains` checks — prefer `Set`
+- Flag `flow.collect {}` re-subscribing on every recomposition in Jetpack Compose — use `collectAsStateWithLifecycle`
+- Flag `Dispatchers.IO` used for CPU-bound work — use `Dispatchers.Default`
+- Flag `suspend` functions calling non-suspend blocking APIs directly — wrap with `withContext(Dispatchers.IO)`
+
+---
+
+## Idioms and Best Practices
+
+### Null Safety
+- Prefer safe call (`?.`) and Elvis operator (`?:`) over `!!`
+- Use `requireNotNull()` / `checkNotNull()` with a descriptive message when null means a programming error
+- Prefer `val` over `var` — immutability by default
+
+### Modern Kotlin
+- Prefer `data class` for value carriers
+- Prefer `sealed class` / `sealed interface` for exhaustive `when` expressions
+- Prefer extension functions over utility classes
+- Prefer `object` declarations for singletons

package/core/shared/skills/do-code-review/languages/php.md

@@ -0,0 +1,109 @@
+---
+language: php
+extensions: [".php", ".phtml", ".php3", ".php4", ".php5", ".phps"]
+---
+
+# PHP — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only PHP-specific rules and idioms.
+
+---
+
+## PR Analyzer — PHP Risk Signals
+
+- `var_dump` / `print_r` / `echo` debug statements left in production code
+- `@` error suppression operator — masks real errors; verify it is justified
+- `// phpcs:ignore` / `// phpstan-ignore` comments — verify they are justified
+- Hardcoded credentials, database passwords, or API keys in source
+- `eval()` anywhere — almost always a security issue
+- `$_GET` / `$_POST` / `$_REQUEST` / `$_COOKIE` used without sanitization
+
+---
+
+## Code Quality — PHP Checks
+
+- Missing type declarations on function parameters and return types
+- `mixed` return type used broadly — tighten to specific types
+- Global variables (`global $var`) — pass dependencies explicitly
+- Long functions (>50 lines) — PHP functions tend to accumulate logic
+- `isset()` / `empty()` used to mask type errors instead of fixing the root cause
+- Missing `strict_types=1` declaration at the top of the file
+
+---
+
+## Security
+
+- Flag `$_GET` / `$_POST` / `$_REQUEST` used directly in SQL queries — require PDO prepared statements
+- Flag `mysqli_query($conn, "SELECT ... WHERE id = " . $_GET['id'])` — SQL injection
+- Flag `echo $_GET['name']` or any unescaped output — XSS; use `htmlspecialchars()` with `ENT_QUOTES`
+- Flag `include` / `require` with user-controlled paths — local/remote file inclusion
+- Flag `eval()` — remote code execution risk; no legitimate use in application code
+- Flag `shell_exec` / `exec` / `system` / `passthru` with user-controlled input — command injection
+- Flag `unserialize()` on untrusted data — arbitrary object instantiation and code execution
+- Flag `move_uploaded_file` without MIME type validation and extension whitelist — file upload attack
+- Flag `header("Location: " . $_GET['url'])` without validation — open redirect
+- Flag missing CSRF token validation on state-changing form endpoints
+
+---
+
+## Async / Concurrency
+
+- Flag long-running synchronous operations in a request cycle — offload to a queue (Laravel Queue, RabbitMQ)
+- Flag `sleep()` used inside a request handler — blocks the PHP-FPM worker
+- Flag shared mutable state in `static` properties accessed across requests in long-running processes (Swoole, RoadRunner)
+- Flag missing idempotency in queued jobs — jobs can be retried on failure
+
+---
+
+## Resource Management
+
+- Flag database connections not closed or returned to the pool (`$pdo = null` or `$conn->close()`)
+- Flag `fopen` / `fwrite` without a matching `fclose` on all paths
+- Flag `curl_init` without `curl_close` — leaks the curl handle
+- Flag unbounded file uploads with no size or type restriction
+- Flag sessions not explicitly closed (`session_write_close()`) before long operations — session locking blocks other requests
+
+---
+
+## Exception Handling
+
+- Flag empty `catch` blocks — swallowed exceptions
+- Flag `catch (Exception $e) {}` without logging — silent failure
+- Flag `die()` / `exit()` used for error handling in library code — use exceptions
+- Flag `@` operator used to suppress errors from functions that can fail — check return values instead
+- Flag `trigger_error` used in new code — prefer exceptions
+
+---
+
+## Performance
+
+- Flag N+1 Eloquent / Doctrine queries — use eager loading (`with()`, `load()`, `join`)
+- Flag `count($array)` called repeatedly in a loop condition — cache the result
+- Flag `array_push($arr, $val)` — use `$arr[] = $val` which is faster
+- Flag `in_array` on large arrays without the strict third argument — use `isset` on a flipped array for O(1) lookup
+- Flag `file_get_contents` on remote URLs in a request cycle — use an HTTP client with timeout and async where possible
+- Flag Eloquent `all()` without pagination — loads entire table into memory
+
+---
+
+## Idioms and Best Practices
+
+### Type Safety
+- Always declare `declare(strict_types=1)` at the top of every file
+- Use union types (`int|string`) and nullable types (`?string`) rather than `mixed`
+- Use typed properties on classes — avoid untyped `public $foo`
+- Use constructor promotion for simple value objects
+
+### Modern PHP (8.x)
+- Prefer `match` expressions over `switch` — strict comparison, no fall-through
+- Use named arguments for functions with many optional parameters
+- Use `enum` for fixed sets of values instead of class constants
+- Use `readonly` properties for immutable data
+- Use nullsafe operator (`?->`) instead of nested `isset` checks
+- Use `first-class callable syntax` (`strlen(...)`) instead of string references
+
+### Laravel / Symfony Specific
+- Keep controllers thin — logic belongs in service classes or action classes
+- Use form requests for validation — never validate in the controller directly
+- Prefer Eloquent relationships over manual joins for readability
+- Flag raw queries where the ORM can express the same intent safely

package/core/shared/skills/do-code-review/languages/python.md

@@ -0,0 +1,94 @@
+---
+language: python
+extensions: [".py"]
+---
+
+# Python — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Python-specific rules and idioms.
+
+---
+
+## PR Analyzer — Python Risk Signals
+
+- `print()` statements left in production code
+- `# noqa` and `# type: ignore` comments — verify they are justified
+- `eval()` / `exec()` with any user-controlled input
+- `pickle` used to deserialize untrusted data
+- Hardcoded credentials or tokens in source
+
+---
+
+## Code Quality — Python Checks
+
+- Bare `except:` or `except Exception:` swallowing silently
+- Mutable default arguments (`def foo(items=[])`) — shared across calls
+- `import *` — pollutes namespace and hides dependencies
+- Missing type hints on public functions and methods
+- `assert` used for runtime validation — stripped by `-O` flag
+
+---
+
+## Security
+
+- Flag `eval()` / `exec()` with any user-controlled input
+- Flag `pickle.loads()` on untrusted data — use `json` or `msgpack`
+- Flag `subprocess` calls with `shell=True` and user input
+- Flag `flask.render_template_string()` with user data (SSTI)
+- Flag `SECRET_KEY` / `DEBUG = True` committed to source
+
+---
+
+## Async
+
+- Flag `asyncio.get_event_loop().run_until_complete()` inside an already-running loop
+- Flag mixing `threading` and `asyncio` without a clear bridge (`run_in_executor`)
+- Flag CPU-bound work inside an `async def` without offloading to `ProcessPoolExecutor`
+- Flag `time.sleep()` inside async functions — use `await asyncio.sleep()`
+
+---
+
+## Resource Management
+
+- Flag `open()` not used as a context manager (`with open(...) as f`)
+- Flag `requests.Session` created per-request instead of shared/reused
+- Flag database connections not closed or returned to a pool on all paths
+- Flag large files read entirely into memory with `.read()` — prefer streaming / chunked reads
+
+---
+
+## Exception Handling
+
+- Flag bare `except:` — catches `BaseException` including `KeyboardInterrupt` and `SystemExit`
+- Flag `except Exception: pass` — silently swallows errors
+- Flag re-raising with `raise e` instead of `raise` — loses the original traceback
+- Flag `except` clause too broad when the `try` block covers multiple operations with different failure modes — split them
+
+---
+
+## Performance
+
+- Flag `+` string concatenation in loops — use `"".join()`
+- Flag repeated `re.compile()` inside a loop — compile once at module level
+- Flag `list.append()` in a loop where a list comprehension would be more efficient
+- Flag `in` membership tests on `list` where the collection is large — use `set`
+- Flag loading entire large files into memory — prefer streaming or chunked reads
+
+---
+
+## Idioms and Best Practices
+
+### Type Safety
+- All public functions and methods should have type annotations
+- Prefer `X | None` (Python 3.10+) over `Optional[X]`
+- Use `TypedDict` or `dataclass` over plain `dict` for structured data
+
+### Modern Python (3.10+)
+- Prefer `match` statements over long `if/elif` chains
+- Prefer `dataclass` or `NamedTuple` over plain classes for data carriers
+- Prefer `pathlib.Path` over `os.path` for file operations
+- Prefer f-strings over `.format()` or `%` formatting
+
+### None Safety
+- Prefer explicit `if x is None` over falsy checks when `0` or `""` are valid values
+- Flag functions returning `None` implicitly — make it explicit or raise