# Engineering Standards

The single, authoritative home for the standards that apply to **every** Quber
ticket and PR. These used to be pasted into each Jira ticket; they are stated
here **once** so tickets can link to them instead of repeating them.

A ticket references this document with one line — `Standards: see
docs/ENGINEERING_STANDARDS.md` — and spends its own body on what is *specific*
to that ticket.

- [Functional Evidence](#functional-evidence) — what every PR must demonstrate
- [Definition of Done](#definition-of-done) — the universal bar for "complete"
- [Technical Standards](#technical-standards) — code-level expectations

---

## Functional Evidence

Every PR must show the change works against **real data**, not that it merely
compiles. Evidence requirements are universal and live here; the evidence
*itself* is specific to each ticket and belongs in that ticket's PR and Current
State.

### What counts as evidence

1. **Real production / realistic data.** Use actual financial documents
   (e.g. `VISA_991_Q126.pdf`, the documents under `inputs/`), not test fixtures
   from `tests/fixtures/`. Show file names, page numbers, sizes, and results.
2. **Actual usage workflows.** Demonstrate the feature working end to end as the
   acceptance criteria describe, integrated with the existing pipeline.
3. **Concrete, measurable results.** Specific identifiers and quantities —
   page numbers, accuracy scores, table counts, durations — plus sample output.
4. **End-to-end verification.** Show it works in application context, that
   dependencies actually run, and that nothing existing regressed.

### How evidence attaches to a ticket

- **By acceptance criterion.** Each AC states how to verify it; the PR shows the
  result for that AC. In the ticket, fold the *result* into Current State and
  mark the AC verified (see [ISSUES_SPEC.md](ISSUES_SPEC.md)).
- **Bugs** additionally show reproduction (the broken behavior before the fix)
  and regression coverage (related workflows still pass).

> The PR is where evidence lives. Tickets do **not** carry static evidence
> checklists — those were scaffolding for less-mature automation and are gone.

---

## Definition of Done

The universal bar. A change is done when:

- Code implemented, and **functional evidence provided for each acceptance
  criterion** in the PR.
- Tests added or updated and passing.
- Type checking clean — `pyright --strict`, zero errors.
- Linting clean — `ruff check`, zero errors.
- Logfire instrumentation added for key operations.
- Reviewed, approved, and merged to `main`.

Tickets do not restate this list. Reference it; meet it.

---

## Technical Standards

The code-level expectations every ticket inherits.

### Code quality

- **Type checking:** `pyright --strict` (zero errors).
- **Linting:** `ruff check` (zero errors).
- **Testing:** `pytest`; meaningful coverage of new behavior.

### Architecture

- **Protocols** for abstractions; type a consuming call site against any new
  Protocol in the same change (no unused contracts).
- **Pydantic** models, frozen/immutable where appropriate.
- **PydanticAI** for all LLM interactions.
- **Logfire** instrumentation for key operations.

### Development

- **Python 3.13+**.
- **async/await** for I/O; async owns the bare name, sync gets a `_sync` suffix.
- **Configuration** via `Settings` (Pydantic Settings); environment variables
  override defaults, never hardcode secrets.

---

## Related

- [ISSUES_SPEC.md](ISSUES_SPEC.md) — how Jira tickets are structured
- [GITHUB_WORKFLOW_SPEC.md](GITHUB_WORKFLOW_SPEC.md) — branch/PR conventions and
  PR-side functional evidence requirements