amare/openspec/specs/quality-gates/spec.md

quality-gates Specification

Purpose

Define Composer quality scripts, architecture boundaries, PostgreSQL-backed feature tests, and the five blocking CI jobs including browser visual and accessibility 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, the visual regression assertions and the automated accessibility checks for public routes, and MUST run in assertion mode without regenerating baselines (SPEC §13.4, §13.5, §13.8, §14.1).

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 visual and accessibility assertions

• WHEN the browser CI job runs
• THEN it MUST execute the visual regression suite and the accessibility suite
• AND a failing snapshot 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 screenshots, snapshot diffs, application logs and browser logs as artifacts