LorenEteval_Furious/.github/AGENTS.md

# Release workflow guidance

Inherit the [nearest parent guide](../AGENTS.md).
This scope owns build, artifact and publication evidence. Source tests, imports, packaged behavior and
release eligibility follow their actual jobs and dependencies.
Read `.github/workflows/deploy-pypi.yml` with `tests/README.md`; paths are relative to this source tree's root.

## Publication and matrix contract

- `workflows/deploy-pypi.yml` is both packaging coverage and the publication graph. Pull requests and ordinary pushes
  build artifacts; tag pushes additionally publish Python distributions, create the GitHub release, and enable the
  dependent WinGet flow. Preserve permission, secret, environment, `if`, and `needs` boundaries.
- `workflows/matrix-build.yml` owns the shared binary matrix, called by `workflows/deploy-pypi.yml` and also run hourly or
  manually. Its standalone runs build, verify, and upload artifacts with read-only repository permissions; publication
  remains in `workflows/deploy-pypi.yml`. The WinGet publisher's installer selection is another explicit contract:
  validate its filename filter against produced artifacts and the intended manifest architectures. Editing an
  individual downstream manifest PR does not change future automatic publication.
- Treat each matrix row as a supported product target with explicit runner OS/architecture, Python, Qt/PySide source,
  native-binding toolchain, compatibility floor, `Deploy.py` output, and upload pattern. Artifact names and architecture
  checks must agree; never infer target architecture from the host label alone.
- Current target-specific checks are intentional: Linux checks the Essentials-only/no-WebEngine build and its
  Flatpak native dependency closure; macOS checks WebEngine frameworks, helpers, resources, relocation, and signing;
  Windows checks native imports and packaged PE machine types, with a separate Windows 7 compatibility toolchain.
  These assertions establish artifact properties, not complete application behavior on those platforms.
  Change an exception only with evidence from the affected target. Binary jobs filter shared requirements before
  installing target-specific Qt/native bindings; copying the ordinary package dependency list into those jobs can
  reintroduce Addons on Linux or replace a compatibility build. Review the effective installed set, not just the
  checked-in requirements.

## Workflow engineering

- Keep packaging declarations synchronized with `Deploy.py`, `pyproject.toml`, `setup.py`, and `requirements.txt`.
  The Python floor advertised by package metadata is a separate claim from the interpreter versions exercised by CI;
  newer matrix rows cannot prove that floor. Likewise, successful Qt imports do not prove event-loop or binding-call
  compatibility. Default-to-newest dependencies/assets still need recorded provenance and deterministic assertions
  at ABI/feature boundaries; pin or checksum external build tools where the workflow establishes that boundary.
  Audit evaluated generic bases and import-time standard-library APIs as well as syntax and wheel availability.
  `from __future__ import annotations` does not defer class-base evaluation; test cold imports on a claimed minimum
  interpreter before treating metadata classifiers or a newer CI row as evidence for that minimum.
- Coordinate explicit native pins across manifests, source-build/wheel-install steps, and API assertions. When native
  provenance is exported, compare it with the intended upstream revision as well as distribution metadata.
  Constructing and closing an engine validates a different boundary from starting a privileged TUN interface.
- Interpreter compatibility jobs install dependency versions that actually support each interpreter, then exercise
  cold imports and real behavior. Grammar checks or newer-interpreter simulations do not substitute for those jobs.
  Keep the full cross-platform regression suite distinct from focused version checks, and make required version
  jobs part of the publication dependency graph rather than treating artifact imports as equivalent coverage.
- Resolve the effective shell at the step, including workflow/job defaults and explicit overrides. Matrix and
  publication workflows default to Bash, while native Windows dependency/architecture steps explicitly use PowerShell;
  source tests use runner defaults. Syntax and environment assignment must match that effective shell. Keep
  OS/architecture conditions on the step that owns the difference.
- Flatpak checks run inside the installed sandbox, inspect the application's required native closure rather than every
  unused Qt plugin, and fail before upload. Do not mask an actually loadable plugin/runtime mismatch with a broad allowlist.
- Generated helper files, downloaded SDKs/assets, build directories, and local bundles are workflow inputs; do
  not commit them. Regeneration does not authorize removing preserved guidance scopes or user-owned artifacts;
  deliberate cleanup follows the requested scope and checked target paths. Never expose credentials or enable
  publication from untrusted pull-request code.

## Verification

- Validate YAML and every affected expression/shell. Trace each changed matrix row through dependency installation,
  source/native import checks, Nuitka/installer output, packaged architecture/dependency checks, artifact upload, and tag
  gates. When a target cannot run locally, add a narrow CI assertion that fails before publication with a useful reason.
- `workflows/source-tests.yml` separates full cross-platform source unittest discovery from focused Linux
  interpreter-version checks. The latter use compatible Qt/native wheel pins, dependency consistency, native-binding
  imports without starting runtimes, application compilation, cold imports and real compatibility behavior. These
  checks do not certify the entire suite on every version.
  Default source discovery includes regular stress but leaves the explicitly enabled very-heavy classes skipped.
  Standalone benchmarks and compiled lifecycle probes are separate entry points; neither runs merely because the
  source job or binary matrix succeeds. Check `tests/README.md` for the effective opt-ins and invocation boundaries.
  The reusable workflow is a required dependency of PyPI publication through `workflows/deploy-pypi.yml`, so its
  version matrix must also pass. It can run manually. Hourly binary builds retain their separate artifact scope. Source tests do not establish packaged behavior or Python/Qt
  floors beyond their matrix. Do not call an artifact build a regression-test pass; use `tests/README.md` for
  source verification. The source suite's offscreen Qt environment exercises widgets and event delivery, not native
  tray integration, privilege prompts, or an installed application's host effects. Follow actual `needs` and tag gates
  back to required checks; upload success alone does not establish release eligibility. A diagnostic Nuitka build
  with different compiler/runtime flags is separate evidence from the ordinary release configuration; exercise the
  latter before claiming a packaged defect resolved. Run artifact checks with paths and working directories
  that cannot accidentally import the source checkout or development environment; the selected distribution
  must supply the modules, native libraries, metadata, and resources being verified.
  Binary jobs can produce/upload artifacts independently of source-test completion; follow the publication job's
  actual prerequisites rather than assuming every uploaded artifact already passed the source suite. Native-binding
  API checks must avoid creating host interfaces and stay distinct from privileged TUN smoke tests.
- Revalidate version/architecture claims against the current matrix instead of duplicating all pins here. Record
  which workflow invocation and effective dependency set produced an artifact; a passing standalone binary job
  does not inherit source-test evidence from a different invocation. When topology changes, follow every consumer
  through upload and publication and update this scope.