manoel-freitas/amare
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs: sync OpenSpec archives and propose foundation parity

Browse Source 
Archive completed public-site and production-provider changes into main specs, remove duplicate active changes, and add complete-foundation-parity so Phase 0 staging and remaining foundation gaps block Phase 2 cleanly.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
manoel freitas
2026-08-01 21:55:04 -03:00
parent cafb1167ac
commit 9dd6fcf409
53 changed files with 885 additions and 828 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
openspec/changes/archive/2026-07-30-build-public-site/specs/content-media/spec.md Normal file
View File

@@ -0,0 +1,52 @@
## ADDED Requirements
### Requirement: Public images are served in responsive variants
The system SHALL generate or serve responsive variants for public content images (service covers, portfolio covers and gallery, testimonial photos) and reference them with `srcset` and `sizes` so browsers download an appropriately sized file (SPEC §6.4). Variant generation MUST happen on upload, not on each request.
#### Scenario: Variants are produced on upload
- **WHEN** an admin uploads a public content image
- **THEN** responsive variants MUST be generated and stored alongside the original
- **AND** the database MUST keep only paths, never binary data
#### Scenario: Public markup offers multiple sources
- **WHEN** a public page renders a content image
- **THEN** the `img` element MUST expose `srcset` with the available variants
- **AND** MUST expose a `sizes` attribute matching the layout
#### Scenario: Missing variant falls back to the original
- **GIVEN** an image stored before variant generation existed
- **WHEN** it is rendered on a public page
- **THEN** the original file MUST be used without breaking the page
### Requirement: Public images avoid layout shift and defer offscreen loading
Public content images SHALL reserve their space through explicit `width` and `height` (or equivalent aspect-ratio styling) and MUST use `loading="lazy"` when rendered below the fold. Above-the-fold hero imagery MUST NOT be lazy loaded (SPEC §6.4, §6.6).
#### Scenario: Offscreen image is lazy loaded
- **WHEN** a page renders an image below the first viewport
- **THEN** the `img` element MUST carry `loading="lazy"`
#### Scenario: Hero image loads eagerly
- **WHEN** the home hero image is rendered
- **THEN** it MUST NOT carry `loading="lazy"`
#### Scenario: Dimensions are reserved
- **WHEN** any public content image is rendered
- **THEN** width and height (or aspect ratio) MUST be declared so layout does not shift after load
### Requirement: Production images are not served from ephemeral container disk
Public image variants SHALL be stored on the configured filesystem disk (S3-compatible in production) and referenced by URL, so a container restart or redeploy does not lose media (SPEC §6.4).
#### Scenario: Media survives container replacement
- **GIVEN** production uses the S3-compatible disk
- **WHEN** the application container is replaced
- **THEN** previously uploaded images and variants MUST remain reachable

90
openspec/changes/archive/2026-07-30-build-public-site/specs/public-seo/spec.md Normal file
View File

@@ -0,0 +1,90 @@
## ADDED Requirements
### Requirement: Every public page emits title, description and canonical
The system SHALL render a unique `<title>`, a `<meta name="description">` and a `<link rel="canonical">` on every public route (SPEC §6.6, §19). Portfolio cases MUST use `meta_title`/`meta_description` when filled and fall back to title/summary otherwise. Pages without page-level metadata MUST fall back to `default_meta_title` and `default_meta_description` from `site_settings`.
#### Scenario: Page-level metadata overrides defaults
- **GIVEN** a published case with `meta_title` and `meta_description` filled
- **WHEN** a visitor loads the case detail
- **THEN** the rendered title and description MUST use the case values
#### Scenario: Missing metadata falls back to site defaults
- **GIVEN** a published case without `meta_title`
- **WHEN** a visitor loads the case detail
- **THEN** the rendered title MUST be derived from the case title
- **AND** the description MUST fall back to the case summary or the site default
#### Scenario: Canonical points to the absolute route URL
- **WHEN** any public page is rendered
- **THEN** the canonical URL MUST be the absolute URL of that route without query parameters
### Requirement: Open Graph metadata is emitted for sharing
The system SHALL emit Open Graph tags (`og:title`, `og:description`, `og:type`, `og:url`, `og:image`) on public pages. The image MUST use the page cover image when available and `default_og_image_path` from `site_settings` otherwise.
#### Scenario: Case detail uses its cover as OG image
- **GIVEN** a published case with a cover image
- **WHEN** the case detail is rendered
- **THEN** `og:image` MUST reference the case cover image URL
#### Scenario: Pages without cover use the default OG image
- **WHEN** a page without its own image is rendered
- **THEN** `og:image` MUST reference `default_og_image_path`
### Requirement: Sitemap and robots are served by the application
The system SHALL serve `/sitemap.xml` listing the home, institutional routes, the services listing, the portfolio listing and every published case slug with its last modification date. `/robots.txt` MUST be served by an application route referencing the sitemap URL.
#### Scenario: Sitemap contains only published slugs
- **GIVEN** one published case and one draft case
- **WHEN** `/sitemap.xml` is requested
- **THEN** the response MUST include the published slug
- **AND** MUST NOT include the draft slug
#### Scenario: Newly published case enters the sitemap
- **WHEN** an admin publishes a case
- **THEN** the case slug MUST appear in `/sitemap.xml` on the next request
#### Scenario: Robots references the sitemap
- **WHEN** `/robots.txt` is requested
- **THEN** the response MUST be `text/plain`
- **AND** MUST contain the absolute `/sitemap.xml` URL
### Requirement: Basic structured data is emitted where applicable
The system SHALL emit JSON-LD structured data: `Organization` on the home using `site_settings`, and `Article` or equivalent creative work on the case detail.
#### Scenario: Home exposes organization data
- **WHEN** the home is rendered
- **THEN** a JSON-LD block of type `Organization` MUST be present with brand name and contact data
#### Scenario: Structured data is valid JSON
- **WHEN** any public page emits JSON-LD
- **THEN** the script content MUST parse as valid JSON
### Requirement: Analytics script is injected only when explicitly enabled
The system SHALL render the analytics snippet from `site_settings` only when `analytics_enabled` is true and the script field is non-empty (WEB-06). Analytics MUST be disabled by default.
#### Scenario: Analytics disabled emits nothing
- **GIVEN** `analytics_enabled` is false
- **WHEN** any public page is rendered
- **THEN** the analytics snippet MUST NOT appear in the HTML
#### Scenario: Analytics enabled injects the configured snippet
- **GIVEN** `analytics_enabled` is true and a snippet is configured
- **WHEN** a public page is rendered
- **THEN** the snippet MUST be present exactly once

115
openspec/changes/archive/2026-07-30-build-public-site/specs/public-site-pages/spec.md Normal file
View File

@@ -0,0 +1,115 @@
## ADDED Requirements
### Requirement: Public routes serve published content without authentication
The system SHALL expose the public routes of SPEC §5.1: `home` (`/`), `services.index` (`/servicos`), `portfolio.index` (`/portfolio`), `portfolio.show` (`/portfolio/{slug}`), `about` (`/sobre`), `contact` (`/contato`) and `privacy` (`/privacidade`). Every public route MUST respond without authentication and MUST NOT expose unpublished content, internal fields, or internal notes (SPEC §19).
#### Scenario: Guest reaches every public route
- **WHEN** an unauthenticated visitor requests any public route
- **THEN** the response status MUST be 200
- **AND** no redirect to `/admin/login` MUST occur
#### Scenario: Unpublished content is invisible
- **GIVEN** a service, portfolio case, or testimonial with `published_at` null
- **WHEN** a visitor loads the corresponding public page
- **THEN** the record MUST NOT appear in the rendered output
#### Scenario: Unpublished case detail returns 404
- **GIVEN** a portfolio case saved as draft
- **WHEN** a visitor requests `/portfolio/{slug}` for that case
- **THEN** the response status MUST be 404
#### Scenario: Published case detail becomes reachable
- **GIVEN** a portfolio case saved as draft
- **WHEN** an admin fills the required fields and publishes the case
- **THEN** `/portfolio/{slug}` MUST respond 200
- **AND** the case MUST appear in the `/portfolio` listing
### Requirement: Home renders the editorial structure from CMS content
The home page SHALL render, in the order defined by SPEC §6.2, header/navigation, hero, featured visual proof, services summary, working method, selected cases, testimonials, final briefing CTA, and footer with contact, social links and legal links (WEB-01). Hero copy, brand name and contact data MUST come from `site_settings`; services, cases and testimonials MUST come from published records.
#### Scenario: Published content is displayed in configured order
- **GIVEN** published services, cases and testimonials exist
- **WHEN** a visitor loads the home
- **THEN** the published content MUST be displayed following the `sort_order` and featured flags
- **AND** the hero MUST show the values stored in `site_settings`
#### Scenario: CTA leads to the briefing page
- **WHEN** a visitor activates the primary or final CTA on the home
- **THEN** the visitor MUST be taken to the `contact` route
#### Scenario: Empty content does not break the home
- **GIVEN** no published services, cases or testimonials
- **WHEN** a visitor loads the home
- **THEN** the response MUST be 200
- **AND** the affected sections MUST be omitted instead of rendering empty containers
#### Scenario: Home has no console errors
- **WHEN** the home is loaded in a real browser at desktop and mobile viewports
- **THEN** the browser console MUST contain no JavaScript errors
### Requirement: Listing and detail pages exist for catalog content
The system SHALL render a services listing (WEB-02) and a portfolio listing plus case detail (WEB-03). The case detail MUST present summary, event type, optional city/venue/date, challenge, solution, optional result, cover image and the ordered gallery.
#### Scenario: Services listing shows published services
- **WHEN** a visitor loads `/servicos`
- **THEN** every published service MUST be listed with title and summary in `sort_order`
#### Scenario: Gallery respects stored order
- **GIVEN** a published case with multiple gallery images
- **WHEN** a visitor loads the case detail
- **THEN** the images MUST be rendered ordered by `sort_order`
#### Scenario: Listings paginate open-ended growth
- **WHEN** the number of published cases exceeds the page size
- **THEN** `/portfolio` MUST paginate instead of rendering all records
### Requirement: Institutional and error pages have brand identity
The system SHALL provide the Sobre and Política de privacidade pages and branded error pages (WEB-07). The 404 page MUST use the public layout, and the 500 page MUST NOT expose stack traces or internal details when `APP_DEBUG` is false.
#### Scenario: Unknown URL renders branded 404
- **WHEN** a visitor requests a non-existent public URL
- **THEN** the response status MUST be 404
- **AND** the page MUST use the public layout and offer navigation back to the home
#### Scenario: Server error hides internals in production
- **GIVEN** `APP_DEBUG` is false
- **WHEN** an unhandled exception occurs on a public route
- **THEN** the response MUST be a generic branded error page
- **AND** MUST NOT contain a stack trace, file path, or environment variable
### Requirement: Contact page presents contact data as briefing placeholder
The `contact` route SHALL render the contact page using `site_settings` (e-mail, phone, city, social links) so the home CTA has a valid destination before the briefing form exists. The page MUST NOT create leads in this change.
#### Scenario: Contact page shows configured contact data
- **WHEN** a visitor loads `/contato`
- **THEN** the e-mail and phone stored in `site_settings` MUST be displayed
- **AND** no lead record MUST be created
### Requirement: Public pages avoid N+1 queries
Public pages SHALL load related content with explicit eager loading through dedicated read Queries in the Application layer. Rendering a page MUST NOT issue one query per related record (SPEC §19).
#### Scenario: Case detail loads gallery in bounded queries
- **WHEN** a case detail page with many gallery images is rendered
- **THEN** the gallery MUST be loaded with eager loading
- **AND** the query count MUST NOT grow with the number of images

21
openspec/changes/archive/2026-07-30-build-public-site/specs/quality-gates/spec.md Normal file
View File

@@ -0,0 +1,21 @@
## MODIFIED Requirements
### 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

51
openspec/changes/archive/2026-07-30-build-public-site/specs/visual-regression/spec.md Normal file
View File

@@ -0,0 +1,51 @@
## ADDED Requirements
### Requirement: Public screens have desktop and mobile visual baselines
The system SHALL keep versioned screenshot baselines for the public screens available in this phase (SPEC §13.5): Home, Serviços, Portfólio and Detalhe do portfólio, at 1440×1000 desktop and 390×844 mobile. A rendering change that alters those screens MUST fail the browser suite until the diff is reviewed.
#### Scenario: Unintended visual change fails the suite
- **GIVEN** approved baselines exist
- **WHEN** a code change alters the rendering of a covered screen
- **THEN** the visual assertion MUST fail and report the diff
#### Scenario: Both viewports are covered
- **WHEN** the visual suite runs
- **THEN** each covered screen MUST be asserted at 1440×1000 and 390×844
### Requirement: Visual runs are deterministic
Visual runs SHALL be deterministic per SPEC §13.5: fixed Chromium and Linux image, fixed viewport, timezone `America/Fortaleza`, locale `pt-BR`, fonts installed in the image, frozen clock, deterministic seed, animations and transitions disabled, and no dependency on external network.
#### Scenario: Repeated run without code change produces no diff
- **WHEN** the visual suite runs twice against the same commit and seed
- **THEN** both runs MUST pass with no pixel diff
#### Scenario: Time-dependent content does not cause drift
- **GIVEN** the clock is frozen and the seed is deterministic
- **WHEN** the suite runs on a different calendar day
- **THEN** rendered dates MUST remain identical to the baseline
#### Scenario: Motion is disabled during capture
- **WHEN** a screenshot is captured
- **THEN** CSS animations and transitions MUST be disabled
### Requirement: Baseline updates are explicit and reviewed
Baselines SHALL only be updated through the explicit `composer visual:update` command, and the resulting diff MUST be reviewed by a human before merge. Baselines MUST NOT be regenerated automatically to make CI pass.
#### Scenario: CI does not regenerate baselines
- **WHEN** the `browser` CI job runs
- **THEN** it MUST run in assertion mode
- **AND** MUST NOT write new baselines
#### Scenario: Developer updates baselines intentionally
- **WHEN** a developer runs `composer visual:update`
- **THEN** the updated baseline files MUST be written to the versioned baseline directory for review

68
openspec/changes/archive/2026-07-30-build-public-site/specs/web-accessibility/spec.md Normal file
View File

@@ -0,0 +1,68 @@
## ADDED Requirements
### Requirement: Public routes have no critical or serious accessibility issues
The system SHALL run automated accessibility checks on the public routes covered by the browser suite (SPEC §6.5, §13.8). A critical or serious issue MUST fail the suite.
#### Scenario: Critical issue blocks the suite
- **WHEN** the automated accessibility check reports a critical or serious issue on a covered route
- **THEN** the browser suite MUST fail and report the offending rule and selector
#### Scenario: Covered routes are checked
- **WHEN** the accessibility suite runs
- **THEN** the home, services listing, portfolio listing and case detail MUST each be checked
### Requirement: Public pages use accessible semantic structure
Public pages SHALL provide semantic landmarks, exactly one `h1` per page, a coherent heading order, alt text on every content image, and visible focus on interactive elements (SPEC §6.5).
#### Scenario: Single h1 per page
- **WHEN** any public page is rendered
- **THEN** exactly one `h1` element MUST be present
#### Scenario: Landmarks are present
- **WHEN** any public page is rendered
- **THEN** `header`, `main`, `nav` and `footer` landmarks MUST be present
#### Scenario: Content images expose alt text
- **WHEN** a page renders a cover or gallery image
- **THEN** the `alt` attribute MUST contain the stored alt text
### Requirement: Public pages are fully keyboard operable
Visitors SHALL be able to reach and activate every interactive element with the keyboard, with a visible focus indicator and a skip link to the main content.
#### Scenario: Keyboard reaches the primary CTA
- **WHEN** a visitor navigates the home with the Tab key
- **THEN** the primary CTA MUST receive focus with a visible indicator
- **AND** activating it with the keyboard MUST navigate to the contact route
#### Scenario: Skip link bypasses navigation
- **WHEN** a visitor focuses the first element of a public page
- **THEN** a skip link to the main content MUST be available
### Requirement: Reduced motion preference is honored
The system SHALL suppress non-essential animation and transition when the user agent reports `prefers-reduced-motion: reduce`.
#### Scenario: Reduced motion disables transitions
- **GIVEN** the browser reports `prefers-reduced-motion: reduce`
- **WHEN** a public page is loaded
- **THEN** decorative transitions and animations MUST NOT run
### Requirement: Public pages emit no console errors
Covered public routes SHALL load without JavaScript console errors in a real browser (SPEC §13.8, §19).
#### Scenario: Console stays clean on covered routes
- **WHEN** a covered public route is loaded in the browser suite
- **THEN** the console MUST contain no error-level messages