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 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