LorenEteval_Furious/AGENTS.md

Furious repository guidance

Source of truth and change discipline

• Treat the checked-out tree as authoritative. Do not resurrect deleted experiments or infer current architecture from old commits or conversations.
• Preserve unrelated working-tree and staged changes. Keep edits scoped to the requested behavior.
• When .codegraph/ exists, use codegraph explore before text search or broad file reading to locate symbols and understand call paths. Use rg for exact follow-up searches.
• Before running Python commands, inspect the repository root for an existing environment matching .venv* or venv*. Prefer its interpreter for project scripts, tests, formatters, generators, and dependency-backed tools whenever usable; do not create or modify an environment unless the task requires it.
• Keep the existing GPL header, from __future__ placement, import grouping, and repository naming style in touched Python files.

Architecture boundaries

• Keep models/configuration documents independent of presentation. Repositories own persistence, services own workflows, controllers own application state/orchestration, and widgets/actions are thin adapters.
• Prefer plugin capabilities and backend factories over protocol/core conditionals in shared application code.
• Treat persisted user configuration as input. Connection-time, test-time, routing, logging, and statistics preparation must operate on explicit runtime copies unless an API is documented as mutating persisted state.
• Application-wide controllers and repositories may be process-lifetime objects; transient UI and temporary process resources must not become accidental global state.
• Keep platform-specific host mutation behind the existing runtime/system abstractions. A feature must remain safe to import and test on unsupported platforms.

Generated artifacts and translations

• Furious/Frozenlib/AppResources.py and Furious/Externals/GenTranslation.py are generated artifacts. Do not hand-maintain them as ordinary source.
• Add user-facing strings through the existing translation-aware widgets/actions and _() extraction conventions. Regenerate translations with Translation.py when translation source changes.
• Pass only static string literals to _(). Runtime-formatted translations such as _(f'{arg} do something...') and _('{arg} do something...'.format(...)) are unsupported; translate static fragments and compose dynamic values outside _() instead.
• Curly braces in extracted strings are reserved for application-constant substitution: Translation.py resolves every {name} through Furious.Frozenlib.Constants. Do not use braces as ordinary runtime-format placeholders.

Verification

• Run the narrowest relevant tests first, then the affected test tier documented in tests/README.md.
• Format only touched Python files with the repository Black configuration, then run Black check mode on the same files.
• For backend/process/platform changes, verify failure cleanup and bounded shutdown as well as the success path.
• For Qt ownership changes, follow Furious/AGENTS.md, use the manage-qt-pyside6-lifetimes skill, and run the relevant lifetime tests; do not use forced garbage collection as a production fix.

Code review rules

• Flag UI code that becomes a second owner of controller/domain state.
• Flag mutation of persisted configuration during runtime preparation.
• Flag new protocol-specific branches in shared managers when a plugin capability can own the behavior.
• Flag edits to generated artifacts without the corresponding generator workflow.