# quality-gates Specification

## Purpose
Define Composer quality scripts, architecture boundaries, PostgreSQL-backed feature tests, and the five blocking CI jobs including browser functional, accessibility and motion coverage.

## Requirements
### Requirement: Standardized Composer test scripts exist

The system SHALL expose Composer scripts equivalent to `test:unit`, `test:feature`, `test:browser`, `test`, and `quality` with the composition defined in SPEC §13.9.

#### Scenario: Developer runs full quality gate locally

- **WHEN** a developer runs `composer quality`
- **THEN** the command executes static analysis, audits, and the applicable test suites

### Requirement: Architecture tests enforce domain boundaries

The system SHALL include Pest architecture tests that verify `App\Domain` uses strict types and does not depend on `App\Filament` or `App\Livewire`.

#### Scenario: Domain layer violates boundary

- **WHEN** code in `App\Domain` imports from `App\Filament` or `App\Livewire`
- **THEN** the architecture test suite MUST fail

### Requirement: CI pipeline blocks merge on five jobs

The system SHALL run a CI pipeline with blocking jobs named `static`, `unit`, `feature`, `browser`, and `container` as defined in SPEC §14.1.

#### Scenario: Static analysis fails on pull request

- **WHEN** a pull request introduces a Pint, PHPStan/Larastan, or Composer audit failure
- **THEN** the `static` job MUST fail and block merge

#### Scenario: Feature tests use PostgreSQL

- **WHEN** the `feature` CI job runs integration tests
- **THEN** the job MUST use PostgreSQL and MUST NOT substitute SQLite

### Requirement: Local feature tests use PostgreSQL

The system SHALL configure `phpunit.xml` so that the Feature test suite uses PostgreSQL with the same connection parameters as CI (`DB_CONNECTION=pgsql`, host, port, database `amare_test`, credentials). Local feature tests MUST NOT default to SQLite `:memory:`.

#### Scenario: Developer runs feature tests locally

- **WHEN** a developer runs `composer test:feature` with PostgreSQL available
- **THEN** tests MUST execute against PostgreSQL
- **AND** MUST NOT silently fall back to SQLite

#### Scenario: Feature tests exercise PostgreSQL-specific types

- **WHEN** feature tests persist records with jsonb columns (e.g., `social_links`)
- **THEN** migrations and constraints MUST be validated against PostgreSQL semantics

### Requirement: Browser tests run against FrankenPHP-served application

The system SHALL execute browser tests using Pest Browser/Playwright against an application served by FrankenPHP in CI. The `browser` job MUST cover the E2E journeys available in the current phase, automated accessibility checks, motion behavior and smoke checks for public routes (SPEC §13.4, §13.7 and §14.1), without pixel comparison.

#### Scenario: Browser job validates served application

- **WHEN** the `browser` CI job runs
- **THEN** tests execute against the built application artifact or equivalent production-like image

#### Scenario: Browser job covers functional, accessibility and motion assertions

- **WHEN** the `browser` CI job runs
- **THEN** it MUST execute the functional browser, accessibility, motion and smoke suites
- **AND** a failing functional assertion or a critical/serious accessibility issue MUST block merge

#### Scenario: Browser failures publish diagnostics

- **WHEN** a browser test fails in CI
- **THEN** the job MUST publish application logs and browser logs as diagnostics

### Requirement: Quality gate includes npm dependency audit

The system SHALL run an npm audit as part of the quality/static gate according to the project policy (SPEC §12.6, §13.9). Audit failure MUST block merge unless an explicit, documented exception exists.

#### Scenario: Vulnerable dependency fails static gate

- **WHEN** `npm audit` reports a policy-violating vulnerability in production dependencies
- **THEN** the static/quality gate MUST fail and block merge

#### Scenario: Developer runs quality locally with audit

- **WHEN** a developer runs `composer quality` (or the documented npm audit step it requires)
- **THEN** the npm audit MUST execute as part of the gate sequence

### Requirement: Domain and Application maintain minimum coverage

The CI unit gate SHALL measure code coverage for `App\Domain` and `App\Application` and MUST fail when either namespace falls below 80% (SPEC §13.7). Views, migrations, generated code, and framework code MUST NOT be required to meet this threshold.

#### Scenario: Coverage drop below threshold blocks merge

- **WHEN** Domain or Application coverage is below 80% on the unit CI job
- **THEN** the job MUST fail

#### Scenario: Coverage ignores non-domain layers

- **WHEN** coverage is computed for the gate
- **THEN** Blade views and migrations MUST NOT be counted toward the Domain/Application threshold

### Requirement: Staging deploy job runs only after blocking CI jobs

When deploying from `main`, the staging deploy workflow MUST require the five blocking CI jobs (`static`, `unit`, `feature`, `browser`, `container`) to succeed before building/pushing the image and triggering Dokploy (SPEC §14.1, §14.3).

#### Scenario: Failed browser job prevents staging deploy

- **WHEN** the `browser` CI job fails on `main`
- **THEN** the staging deploy workflow MUST NOT promote a new image