LorenEteval_Furious/AGENTS.md

Furious repository guidance

Working method

• Treat the checked-out tree as authoritative. Preserve unrelated staged and unstaged work; do not revive deleted experiments or infer architecture from old history.
• If .codegraph/ exists, use codegraph explore before broad text search or file reading. Use rg for exact follow-up searches.
• Before Python work, inspect the repository root for .venv* or venv* and prefer its interpreter when usable. Do not create or modify an environment unless required.
• Keep edits focused. Preserve GPL headers, from __future__ placement, import grouping, repository naming style, and public compatibility unless a deliberate migration is part of the task.

Pythonic design

• Prefer the simplest design that makes ownership, state transitions, failure, and side effects explicit. Readability and one canonical path beat clever indirection or parallel implementations.
• Keep policy close to the layer that owns it: models describe data, repositories persist domain collections, AppSettings persists preferences, services perform workflows, controllers own shared runtime state/orchestration, plugins/backends own protocol-specific behavior, and UI adapts those APIs.
• Make invalid states and boundary failures visible with specific return values, result objects, or exceptions. Catch broadly only at a genuine isolation boundary, log actionable context, and do not silently convert explicit user input into a different behavior.
• Bound external work where the workflow requires responsiveness: network requests, subprocess startup/shutdown, thread joins, and host commands need caller-chosen timeouts or a documented non-GUI execution context. Low-level wrappers such as runExternalCommand() intentionally do not invent a universal timeout. Cleanup must be idempotent, own exact resources, and never search by process name.
• Prefer immutable metadata, pure transformations, dependency injection, and explicit runtime copies. Avoid global mutable state, hidden mutation, duplicated caches, and UI-owned business state.

Repository invariants

• Treat persisted user configuration as input. Connection, routing, testing, logging, TUN, and statistics preparation must not mutate it implicitly; use explicit runtime/derived state unless an API is documented as mutating storage.
• Prefer plugin capabilities/factories over protocol or core conditionals in shared managers. Registries store classes, factories, descriptors, and immutable metadata—not transient UI instances.
• CoreRuntime means one managed proxy-core lifecycle regardless of whether its implementation uses a subprocess, multiprocessing, or an in-process binding. Reserve process terminology for actual operating-system processes and handles.
• Application-wide controllers and repositories may be process-lifetime. Transient UI, network replies, timers, callbacks, and temporary processes must not become accidental global state.
• Keep platform mutation behind Frozenlib/runtime abstractions so unsupported platforms remain safe to import and tests can fully mock host operations.
• Treat secrets, subscription payloads, paths, URLs, and plugin data as untrusted input. Do not log credentials or full sensitive configurations; validate before host or process use.

Generated files and translations

• Furious/Frozenlib/AppResources.py and Furious/Externals/GenTranslation.py are generated. Change their source inputs and run the existing generator instead of hand-maintaining them.
• Add user-facing text through translation-aware controls and _() extraction conventions, then run Translation.py.
• _() normally receives a static string literal. The sole dynamic exception is an f-string made only from bare names in Furious.Frozenlib.Constants; the extractor resolves those constants. Runtime values, attributes, calls, format specifications, and .format(...) inside _() are unsupported.
• Curly braces in extracted strings are reserved for application-constant substitution, not ordinary runtime placeholders.

Verification and review

• Run the narrowest relevant tests first, then the affected tier in tests/README.md. Tests must not touch production settings, networking, routing, TUN, startup registration, or unrelated processes.
• Format only touched Python files with the repository Black configuration and run Black check mode on those files.
• For backend/process/platform work, verify error cleanup and bounded shutdown. For Qt ownership work, follow Furious/AGENTS.md and Furious/Qt/AGENTS.md, use the manage-qt-pyside6-lifetimes skill, and run the relevant lifetime tests.
• Review for duplicated state authorities, mutation of persisted configuration during runtime preparation, broad swallowed errors, unbounded waits/caches, generated-file edits without regeneration, and protocol branches that belong in a capability.