Development and architecture policy

Normative rules for all KOPR development after the R515/C8 canonical convergence.

Current canonical policy Effective baseline: R515. The current public release line is owned by src/kopr/config/release_identity.py and is not duplicated as a fixed value in this documentation. This policy supersedes the post-R410 hybrid-development policy and migration-era instructions.

Authoritative full text: KOPR_DEVELOPMENT_ARCHITECTURE_POLICY_CURRENT.md. The summary below is for navigation; if wording differs, the full policy and current machine-readable tools/architecture/* contracts control.

Mandatory architecture rules

All new implementation belongs under src/kopr/.
Root compatibility files remain non-owning.
Canonical src/kopr code never imports flat-root KOPR modules.
Every behavior has one canonical owner; no duplicate active implementations.
The canonical package remains acyclic.
Layer directions and intentional public APIs are respected.
Do not create generic catch-all modules or wildcard package APIs.
Do not weaken guard budgets/allowlists to hide coupling.
Separate structural work from scientific/user-visible changes unless explicitly planned and qualified together.
Keep the public release label centralized in kopr.config.release_identity.

Required development workflow

python3 tools/architecture/architecture_guard.py

Run the guard before and after production or structural changes. Start from the latest qualified canonical build, identify the canonical owner, classify the risk, define focused/regression qualification in advance, and preserve CLEAN/QA production parity for release artifacts.

Complex work is performed in coherent bounded batches. If unexpected dependency, path, global-state, monkeypatch, Qt, multiprocessing, serialization, compatibility or scientific coupling requires a complex solution, stop expanding the current batch and re-plan the remaining work.

Qualification by risk class

Class	Minimum qualification logic
Documentation-only	Documentation consistency and architecture/documentation checks when ownership/path wording is touched.
Local bug/feature	Architecture guard, focused tests, relevant subsystem regression and GUI/scientific qualification if applicable.
Structural/import/package	Guard, ownership tests, architecture mutation qualification, current frozen regression profile, CLEAN/QA parity, wheel/source/install and launcher qualification as applicable.
Scientific	Applicable runtime/structural gates plus direct reference/invariant tests and explicit unit/time/epoch/frame checks.
GUI	Focused GUI tests, offscreen Qt when useful and native GUI on a capable host when native lifecycle/input/rendering is claimed.
Compatibility-breaking	Explicit break plan, identity/pickle/import/CLI/monkeypatch/source-checkout probes, upgrade and rollback strategy.

Compatibility perimeter

Retained root surfaces preserve explicit historical contracts only. They may delegate, alias, re-export or adapt to canonical owners; they must not contain new product behavior. Removal or semantic retargeting is never routine cleanup and requires its own compatibility-breaking qualification.

Architecture exception procedure

Do not change budgets or allowlists as a first response. An exception must document the concrete need, alternatives, why ownership/API/DI are insufficient, expected coupling, scientific/GUI/persistence/packaging/compatibility risks, qualification, rollback and whether the exception is temporary or a new architecture rule.

Short review checklist

Latest canonical baseline used.
New implementation under src/kopr/.
Root compatibility remains non-owning.
No src/kopr → flat-root import.
No root-to-root edge and no canonical SCC.
One canonical owner and intentional public APIs.
Scientific/GUI/persistence/worker semantics changed only intentionally and qualified.
Architecture guard and risk-appropriate tests pass.
Documentation and machine-readable contracts updated together when architecture changes.
Qualified product-code release identity advanced only within the current Greek series unless explicitly instructed otherwise.

Incremental localization rule

The canonical UI text catalogue is src/kopr/config/translations.py. Localization is incremental, not a broad refactor.

Every new production function that creates or passes user-visible text uses canonical translation keys and translate(...) / local tr(...).
When an existing production function is materially edited, migrate all user-visible string literals in that function during the same batch.
Do not move internal logs, protocol tokens, persistence keys, scientific identifiers or test-only text merely for localization.
Keep the current English UI wording behavior-neutral unless the feature task explicitly changes UX text.
Do not add global mutable language state or a language selector without a separate localization project.
Focused QA must cover key resolution, placeholders, preserved user-visible wording and removal of relevant inline literals in the edited function.

This rule must not expand batch scope; unexpected localization coupling is replanned as a separate bounded batch.