First deployment
This commit is contained in:
@@ -5,11 +5,12 @@ Canonical specification for admin-maintenance-command-suite requirements synced
|
||||
## Requirements
|
||||
|
||||
### Requirement: Unified admin command surface
|
||||
The system SHALL provide a single admin CLI command family exposing maintenance subcommands.
|
||||
The system SHALL provide a single admin CLI command family exposing maintenance subcommands, including permalink-targeted image refetch support.
|
||||
|
||||
#### Scenario: Subcommand discovery
|
||||
- **WHEN** an operator runs the admin command help output
|
||||
- **THEN** available subcommands include refetch-images, clean-archive, clear-cache, clear-news, rebuild-site, regenerate-translations, and fetch
|
||||
- **AND** refetch-images help output documents optional permalink-targeted execution
|
||||
|
||||
### Requirement: Fetch command supports configurable article count
|
||||
The admin fetch command SHALL support an operator-provided article count parameter.
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
## Purpose
|
||||
|
||||
Canonical specification for alternative-image-selection-and-dedupe requirements synced from OpenSpec change deltas.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Refetch selects an alternative image for target article
|
||||
Refetch operations SHALL select an image different from the article's current summary image when a usable alternative exists.
|
||||
|
||||
#### Scenario: Current image is excluded from candidate result
|
||||
- **WHEN** refetch evaluates image candidates for an article
|
||||
- **THEN** the system rejects candidates matching the current summary image identity
|
||||
- **AND** stores a different accepted image candidate when available
|
||||
|
||||
### Requirement: Candidate filtering enforces topical relevance and safety
|
||||
Refetch candidate selection SHALL reject clearly unrelated imagery classes while preserving topic relevance.
|
||||
|
||||
#### Scenario: Unrelated animal/pet candidate is rejected
|
||||
- **WHEN** candidate metadata or source signals indicate unrelated animal/pet imagery
|
||||
- **THEN** the system rejects that candidate for article refetch
|
||||
- **AND** continues evaluating other candidates or fallback paths
|
||||
|
||||
### Requirement: Low-confidence selection falls back to AI-themed default
|
||||
If no candidate satisfies relevance and safety thresholds, the system SHALL use deterministic AI-themed fallback imagery.
|
||||
|
||||
#### Scenario: All candidates rejected
|
||||
- **WHEN** candidate evaluation exhausts without an accepted image
|
||||
- **THEN** the system assigns configured AI-themed fallback image
|
||||
- **AND** records fallback decision path in command output/logs
|
||||
@@ -0,0 +1,39 @@
|
||||
## Purpose
|
||||
|
||||
Canonical specification for article-permalinks-and-deep-link-modal requirements synced from OpenSpec change deltas.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Each news item exposes a permalink
|
||||
The system SHALL expose a stable, shareable permalink for each rendered news item.
|
||||
|
||||
#### Scenario: Per-item permalink rendering
|
||||
- **WHEN** a news item is rendered in hero or feed context
|
||||
- **THEN** the UI provides a permalink target tied to that article context
|
||||
|
||||
#### Scenario: Permalink copy/share usability
|
||||
- **WHEN** a user uses share/copy affordances for an item
|
||||
- **THEN** the resulting URL contains sufficient information to resolve that article on load
|
||||
|
||||
### Requirement: Deep-link loads article modal in open state
|
||||
The system SHALL open the matching article modal when the page is loaded with a valid article permalink, regardless of whether the target is hero or feed content.
|
||||
|
||||
#### Scenario: Valid permalink opens modal
|
||||
- **WHEN** a user lands on homepage with a permalink for an existing article
|
||||
- **THEN** the corresponding article modal is opened automatically
|
||||
- **AND** modal content matches the permalink target
|
||||
|
||||
#### Scenario: Hero permalink opens parity modal
|
||||
- **WHEN** a user lands with a permalink for the current hero article
|
||||
- **THEN** the modal opens with the same structure and behaviors as feed-opened modal
|
||||
- **AND** summary image render path is executed normally
|
||||
|
||||
#### Scenario: Escape closes deep-linked modal
|
||||
- **WHEN** a modal opened from permalink is focused
|
||||
- **THEN** pressing `Escape` closes the modal
|
||||
- **AND** URL deep-link state is cleared consistently
|
||||
|
||||
#### Scenario: Invalid permalink fails safely
|
||||
- **WHEN** permalink article id does not resolve to an existing item
|
||||
- **THEN** modal is not opened
|
||||
- **AND** main page remains fully usable
|
||||
@@ -5,7 +5,7 @@ Canonical specification for article-translations-ml-tm requirements synced from
|
||||
## Requirements
|
||||
|
||||
### Requirement: System generates Tamil and Malayalam translations at article creation time
|
||||
The system SHALL generate Tamil (`ta`) and Malayalam (`ml`) translations for each newly created article during ingestion.
|
||||
The system SHALL generate Tamil (`ta`) and Malayalam (`ml`) translations for each newly created article during ingestion and validate translation quality before persistence.
|
||||
|
||||
#### Scenario: Translation generation for new article
|
||||
- **WHEN** a new source article is accepted for storage
|
||||
@@ -17,6 +17,11 @@ The system SHALL generate Tamil (`ta`) and Malayalam (`ml`) translations for eac
|
||||
- **THEN** the system stores the base article in English
|
||||
- **AND** marks missing translations as unavailable without failing the whole ingestion cycle
|
||||
|
||||
#### Scenario: Translation quality validation failure
|
||||
- **WHEN** generated translation fails language/script sanity or gibberish validation checks
|
||||
- **THEN** the system does not persist invalid translation content for that article-language pair
|
||||
- **AND** records validation failure outcome for diagnostics
|
||||
|
||||
### Requirement: System stores translation variants linked to the same article
|
||||
The system SHALL persist language-specific translated content as translation items associated with the base article.
|
||||
|
||||
|
||||
@@ -5,14 +5,14 @@ Canonical specification for attribution-disclaimer-page requirements synced from
|
||||
## Requirements
|
||||
|
||||
### Requirement: Attribution page discloses AI generation and non-ownership
|
||||
The system SHALL provide an Attribution page with explicit statements that content is AI-generated and not personally authored by the site owner.
|
||||
The system SHALL provide Attribution disclosure content with explicit statements that content is AI-generated and not personally authored by the site owner, including modal-based access from the landing experience.
|
||||
|
||||
#### Scenario: Attribution page title and disclosure content
|
||||
- **WHEN** a user opens the Attribution page
|
||||
- **THEN** the page title clearly indicates attribution/disclaimer purpose
|
||||
- **AND** the body states that content is AI-generated and not generated by the owner as an individual
|
||||
#### Scenario: Attribution disclosure title and body content
|
||||
- **WHEN** a user opens Attribution disclosure content from supported entry points
|
||||
- **THEN** the title clearly indicates attribution/disclaimer purpose
|
||||
- **AND** the body states content is AI-generated and not generated by the owner as an individual
|
||||
|
||||
#### Scenario: Attribution page includes non-involvement statement
|
||||
- **WHEN** a user reads the Attribution page
|
||||
- **THEN** the page explicitly states owner non-involvement in generated content claims
|
||||
- **AND** wording is presented in primary readable content area
|
||||
#### Scenario: Attribution disclosure includes non-involvement statement
|
||||
- **WHEN** a user reads Attribution details
|
||||
- **THEN** the content explicitly states owner non-involvement in generated content claims
|
||||
- **AND** wording appears in primary readable content area
|
||||
|
||||
@@ -5,19 +5,20 @@ Canonical specification for context-aware-image-selection-recovery requirements
|
||||
## Requirements
|
||||
|
||||
### Requirement: Context-aware image query generation
|
||||
Image refetch SHALL construct provider queries from article context including keywords and mood/sentiment cues.
|
||||
Image refetch SHALL construct provider queries from article context by identifying main subject keywords from headline and summary content.
|
||||
|
||||
#### Scenario: Context-enriched query
|
||||
- **WHEN** a queued article is processed for image refetch
|
||||
- **THEN** the system derives query terms from article headline/summary content
|
||||
- **AND** includes mood/sentiment-informed cues to improve relevance
|
||||
- **THEN** the system derives main-subject query terms from article headline and summary
|
||||
- **AND** includes relevance-supporting cues for improved candidate quality
|
||||
|
||||
### Requirement: AI-domain fallback keywords
|
||||
When context extraction is insufficient, the system SHALL use AI-domain fallback keywords.
|
||||
When context extraction is insufficient or confidence is low, the system SHALL use AI-domain fallback keywords.
|
||||
|
||||
#### Scenario: Empty or weak context extraction
|
||||
- **WHEN** extracted context terms are empty or below quality threshold
|
||||
- **THEN** the system applies fallback terms such as `ai`, `machine learning`, `deep learning`
|
||||
- **AND** continues candidate search with deterministic fallback ordering
|
||||
|
||||
### Requirement: Generic AI fallback image on terminal failure
|
||||
If no usable provider image is returned, the system SHALL assign a generic AI fallback image.
|
||||
|
||||
@@ -37,3 +37,11 @@ The system SHALL provide smooth scrolling behavior for in-page navigation and us
|
||||
- **WHEN** users navigate to in-page anchors or equivalent interactions
|
||||
- **THEN** scrolling transitions occur smoothly rather than jumping abruptly
|
||||
- **AND** behavior is consistent across supported breakpoints
|
||||
|
||||
### Requirement: Performance thresholds are continuously validated
|
||||
The system SHALL enforce page-speed and rendering performance thresholds in automated checks.
|
||||
|
||||
#### Scenario: Performance budget gate
|
||||
- **WHEN** performance checks exceed configured budget thresholds
|
||||
- **THEN** CI performance gate fails
|
||||
- **AND** reports identify the regressed metrics and impacted pages
|
||||
|
||||
20
openspec/specs/end-to-end-system-testing/spec.md
Normal file
20
openspec/specs/end-to-end-system-testing/spec.md
Normal file
@@ -0,0 +1,20 @@
|
||||
## Purpose
|
||||
|
||||
Canonical specification for end-to-end-system-testing requirements synced from OpenSpec change deltas.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: End-to-end coverage spans UI, API, and DB effects
|
||||
The system SHALL provide end-to-end tests that validate full workflows across UI, API, and persisted database outcomes.
|
||||
|
||||
#### Scenario: Core user flow E2E
|
||||
- **WHEN** a core browsing flow is executed in E2E tests
|
||||
- **THEN** UI behavior, API responses, and DB side effects match expected outcomes
|
||||
|
||||
### Requirement: Edge-case workflows are covered
|
||||
The system SHALL include edge-case E2E tests for critical failure and boundary conditions.
|
||||
|
||||
#### Scenario: Failure-state E2E
|
||||
- **WHEN** an edge case is triggered (empty data, unavailable upstream, invalid permalink, etc.)
|
||||
- **THEN** system response remains stable and user-safe
|
||||
- **AND** no unhandled runtime errors occur
|
||||
@@ -5,14 +5,29 @@ Canonical specification for footer-policy-links requirements synced from OpenSpe
|
||||
## Requirements
|
||||
|
||||
### Requirement: Footer exposes policy navigation links
|
||||
The system SHALL display footer links for Terms of Use and Attribution on the landing page.
|
||||
The system SHALL display footer controls for Terms of Use and Attribution on the landing page and open their disclosure content in in-page modal dialogs while preserving compact sticky-footer behavior.
|
||||
|
||||
#### Scenario: Footer links visible on landing page
|
||||
#### Scenario: Footer policy controls visible and focusable
|
||||
- **WHEN** a user loads the main page
|
||||
- **THEN** the footer includes links labeled "Terms of Use" and "Attribution"
|
||||
- **AND** links are visually distinguishable and keyboard focusable
|
||||
- **THEN** the footer includes controls labeled "Terms of Use" and "Attribution"
|
||||
- **AND** controls are visually distinguishable and keyboard focusable
|
||||
|
||||
#### Scenario: Footer links navigate correctly
|
||||
- **WHEN** a user activates either policy link
|
||||
- **THEN** the browser navigates to the corresponding policy page
|
||||
- **AND** navigation succeeds without API dependency
|
||||
#### Scenario: Footer policy controls open modal disclosures
|
||||
- **WHEN** a user activates either policy control
|
||||
- **THEN** the system opens the corresponding policy modal
|
||||
- **AND** activation succeeds without full-page navigation dependency
|
||||
|
||||
#### Scenario: Sticky compact footer
|
||||
- **WHEN** user scrolls through content
|
||||
- **THEN** footer remains sticky at viewport bottom
|
||||
- **AND** footer height stays compact enough to avoid readability obstruction
|
||||
|
||||
#### Scenario: Floating back-to-top island
|
||||
- **WHEN** page is scrolled beyond initial viewport
|
||||
- **THEN** a floating back-to-top control is visible
|
||||
- **AND** activating it returns viewport to top smoothly
|
||||
|
||||
#### Scenario: Footer includes optional GitHub and email links
|
||||
- **WHEN** GitHub repository URL and/or contact email are configured
|
||||
- **THEN** footer renders corresponding links without replacing policy controls
|
||||
- **AND** absent values do not break footer layout
|
||||
|
||||
@@ -5,7 +5,7 @@ Canonical specification for hero-display requirements synced from OpenSpec chang
|
||||
## Requirements
|
||||
|
||||
### Requirement: Hero block display
|
||||
The system SHALL display the most recent news item as a featured hero block with full attribution.
|
||||
The system SHALL display the most recent news item as a featured hero block with full attribution and modal-behavior parity, while omitting a dedicated hero permalink affordance.
|
||||
|
||||
#### Scenario: Hero rendering
|
||||
- **WHEN** the page loads
|
||||
@@ -18,8 +18,17 @@ The system SHALL display the most recent news item as a featured hero block with
|
||||
- **THEN** the hero block SHALL automatically update to show the newest item
|
||||
- **AND** the previous hero item SHALL move to the news feed
|
||||
|
||||
#### Scenario: Hero-origin modal consistency
|
||||
- **WHEN** modal opens from hero context (including permalink-triggered entry)
|
||||
- **THEN** modal image, content, and close controls behave consistently with feed-origin modal flows
|
||||
|
||||
#### Scenario: Hero action chrome excludes permalink control
|
||||
- **WHEN** the hero block is rendered
|
||||
- **THEN** no dedicated hero permalink control is displayed
|
||||
- **AND** summary open and source-link actions remain available
|
||||
|
||||
### Requirement: Infinite scroll news feed
|
||||
The system SHALL display news items in reverse chronological order with infinite scroll pagination.
|
||||
The system SHALL display news items in reverse chronological order with infinite scroll pagination and minimal card chrome.
|
||||
|
||||
#### Scenario: Initial load
|
||||
- **WHEN** the page first loads
|
||||
@@ -37,6 +46,11 @@ The system SHALL display news items in reverse chronological order with infinite
|
||||
- **THEN** the system SHALL display "No more news" message
|
||||
- **AND** disable further scroll triggers
|
||||
|
||||
#### Scenario: Card chrome remains minimal
|
||||
- **WHEN** feed cards are rendered
|
||||
- **THEN** redundant small "Link" affordance is not shown
|
||||
- **AND** card still exposes required source and TL;DR interactions
|
||||
|
||||
### Requirement: News attribution display
|
||||
The system SHALL clearly attribute all news content and images to their sources.
|
||||
|
||||
@@ -55,3 +69,4 @@ The system SHALL clearly attribute all news content and images to their sources.
|
||||
- **AND** track page view events on initial load
|
||||
- **AND** track scroll depth events (25%, 50%, 75%, 100%)
|
||||
- **AND** track CTA click events (news item clicks, source link clicks)
|
||||
- **AND** CTA click payload includes both `article_id` and `article_title` when article context is available
|
||||
|
||||
@@ -20,12 +20,14 @@ The hero section SHALL keep an explicit secondary source-link action for externa
|
||||
- **THEN** the system opens the article source URL in a new tab
|
||||
|
||||
### Requirement: Hero metadata readability over images
|
||||
Hero metadata (`LATEST`, relative time, headline, and summary) SHALL remain visually legible across bright and dark images on desktop and mobile.
|
||||
Hero metadata (`LATEST`, relative time, headline, and summary) SHALL remain visually legible across bright and dark images on desktop and mobile, including Tamil and Malayalam rendering paths.
|
||||
|
||||
#### Scenario: Bright image background
|
||||
- **WHEN** the hero image contains bright regions under metadata text
|
||||
- **THEN** overlay and text styles preserve readable contrast for metadata and headline blocks
|
||||
- **AND** readability remains stable for English, Tamil, and Malayalam content
|
||||
|
||||
#### Scenario: Mobile viewport readability
|
||||
- **WHEN** the hero renders on a mobile viewport
|
||||
- **THEN** metadata and title remain readable without overlapping controls or clipping
|
||||
- **AND** Tamil and Malayalam typography remains legible at mobile breakpoints
|
||||
|
||||
@@ -17,14 +17,24 @@ The system SHALL support language-aware content delivery for hero and feed reads
|
||||
- **THEN** the system returns each feed item's headline and summary in the selected language when available
|
||||
- **AND** preserves existing pagination behavior and ordering semantics
|
||||
|
||||
#### Scenario: Tamil and Malayalam rendering quality support
|
||||
- **WHEN** Tamil (`ta`) or Malayalam (`ml`) content is delivered to frontend surfaces
|
||||
- **THEN** payload text preserves script fidelity and Unicode correctness
|
||||
- **AND** frontend presentation hooks can apply readability-focused typography adjustments without changing response shape
|
||||
|
||||
### Requirement: Language fallback to English is deterministic
|
||||
The system SHALL return English source content when the requested translation is unavailable.
|
||||
The system SHALL return English source content when the requested translation is unavailable or fails translation quality validation.
|
||||
|
||||
#### Scenario: Missing translation fallback
|
||||
- **WHEN** a client requests Tamil or Malayalam content for an article lacking that translation
|
||||
- **THEN** the system returns the English headline and summary for that article
|
||||
- **AND** response shape remains consistent with language-aware responses
|
||||
|
||||
#### Scenario: Invalid translation fallback
|
||||
- **WHEN** a client requests Tamil or Malayalam content for an article whose translation failed quality validation
|
||||
- **THEN** the system returns English headline and summary for that article
|
||||
- **AND** avoids returning invalid translated output
|
||||
|
||||
#### Scenario: Unsupported language handling
|
||||
- **WHEN** a client requests a language outside supported values (`en`, `ta`, `ml`)
|
||||
- **THEN** the system applies the defined default language behavior for this phase
|
||||
|
||||
@@ -19,9 +19,24 @@ If provider lookups fail to return a usable summary image, the system SHALL use
|
||||
- **THEN** the system assigns a generic AI fallback image URL/path for summary image
|
||||
|
||||
### Requirement: Fallback behavior remains context-aware first
|
||||
The system SHALL attempt context-aware keyword retrieval before any generic fallback image is selected.
|
||||
The system SHALL evaluate context-aware candidates before fallback and require refetched summary images to be relevant, non-redundant alternatives.
|
||||
|
||||
#### Scenario: Context-aware attempt precedes fallback
|
||||
- **WHEN** summary image selection runs for a news item
|
||||
- **THEN** the system first attempts provider queries from extracted context-aware keywords
|
||||
- **AND** only falls back to generic AI image if these attempts fail
|
||||
- **AND** only falls back to generic AI image if candidate evaluation fails
|
||||
|
||||
#### Scenario: Finance-story relevance guard
|
||||
- **WHEN** article topic contains finance/market terms (for example stocks, shares, plunge, earnings)
|
||||
- **THEN** image selection rejects obviously unrelated animal/portrait outcomes
|
||||
- **AND** system retries with finance-safe query refinements before final fallback
|
||||
|
||||
#### Scenario: Guarded fallback remains deterministic
|
||||
- **WHEN** provider chain cannot return a relevant finance-safe image
|
||||
- **THEN** system uses deterministic generic fallback that is topic-safe
|
||||
- **AND** avoids unrelated imagery classes flagged by guardrails
|
||||
|
||||
#### Scenario: Refetch rejects unrelated and duplicate outcomes
|
||||
- **WHEN** candidate images are evaluated during refetch
|
||||
- **THEN** the system rejects candidates matching current image identity for the same article
|
||||
- **AND** rejects clearly unrelated animal/pet imagery classes before final selection
|
||||
|
||||
18
openspec/specs/permalink-targeted-image-refetch/spec.md
Normal file
18
openspec/specs/permalink-targeted-image-refetch/spec.md
Normal file
@@ -0,0 +1,18 @@
|
||||
## Purpose
|
||||
|
||||
Canonical specification for permalink-targeted-image-refetch requirements synced from OpenSpec change deltas.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Admin image refetch supports permalink targeting
|
||||
The admin image refetch command SHALL support a permalink-targeted execution mode for deterministic single-article remediation.
|
||||
|
||||
#### Scenario: Refetch by permalink
|
||||
- **WHEN** an operator runs refetch-images with a valid permalink target
|
||||
- **THEN** the system resolves permalink identity to the matching article
|
||||
- **AND** executes image refetch for that target without requiring batch mode
|
||||
|
||||
#### Scenario: Invalid permalink target fails clearly
|
||||
- **WHEN** an operator provides a malformed or unresolved permalink target
|
||||
- **THEN** the command exits with actionable error output
|
||||
- **AND** no article image is modified
|
||||
21
openspec/specs/platform-quality-gates/spec.md
Normal file
21
openspec/specs/platform-quality-gates/spec.md
Normal file
@@ -0,0 +1,21 @@
|
||||
## Purpose
|
||||
|
||||
Canonical specification for platform-quality-gates requirements synced from OpenSpec change deltas.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Release quality gates are mandatory
|
||||
The system SHALL enforce mandatory CI quality gates before release.
|
||||
|
||||
#### Scenario: Gate failure blocks release
|
||||
- **WHEN** any required gate fails
|
||||
- **THEN** release pipeline status is failed
|
||||
- **AND** deployment/archive promotion is blocked
|
||||
|
||||
### Requirement: Required gates are explicit and versioned
|
||||
The system SHALL define an explicit set of required gates and versions for tooling.
|
||||
|
||||
#### Scenario: Gate manifest exists
|
||||
- **WHEN** pipeline configuration is evaluated
|
||||
- **THEN** required gates include tests, accessibility, security, and performance checks
|
||||
- **AND** tool versions are pinned or documented for reproducibility
|
||||
31
openspec/specs/policy-disclosure-modals/spec.md
Normal file
31
openspec/specs/policy-disclosure-modals/spec.md
Normal file
@@ -0,0 +1,31 @@
|
||||
## Purpose
|
||||
|
||||
Canonical specification for policy-disclosure-modals requirements synced from OpenSpec change deltas.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Policy disclosures are available as in-page modals
|
||||
The system SHALL present Terms of Use and Attribution content in in-page modal dialogs without requiring full-page navigation from the landing experience.
|
||||
|
||||
#### Scenario: Open Terms modal from footer
|
||||
- **WHEN** a user activates the "Terms of Use" footer control
|
||||
- **THEN** a Terms modal opens in place on the current page
|
||||
- **AND** the underlying page context remains intact
|
||||
|
||||
#### Scenario: Open Attribution modal from footer
|
||||
- **WHEN** a user activates the "Attribution" footer control
|
||||
- **THEN** an Attribution modal opens in place on the current page
|
||||
- **AND** disclosure content is readable in the modal body
|
||||
|
||||
### Requirement: Policy modals are keyboard-safe and dismissible
|
||||
Policy disclosure modals SHALL provide deterministic keyboard and pointer dismissal behavior.
|
||||
|
||||
#### Scenario: Escape closes active policy modal
|
||||
- **WHEN** a policy modal is open and the user presses `Escape`
|
||||
- **THEN** the modal closes
|
||||
- **AND** focus returns to the triggering control
|
||||
|
||||
#### Scenario: Modal focus remains trapped while open
|
||||
- **WHEN** a keyboard-only user tabs while a policy modal is open
|
||||
- **THEN** focus cycles within modal interactive controls
|
||||
- **AND** focus does not escape to background content
|
||||
@@ -5,13 +5,18 @@ Canonical specification for queued-image-refetch-with-backoff requirements synce
|
||||
## Requirements
|
||||
|
||||
### Requirement: Latest-30 queue construction
|
||||
The refetch-images command SHALL enqueue up to the latest 30 news items for processing.
|
||||
The refetch-images command SHALL enqueue up to the latest 30 news items for processing in batch mode and support targeted single-article mode when permalink targeting is provided.
|
||||
|
||||
#### Scenario: Queue population
|
||||
- **WHEN** refetch-images is started
|
||||
- **WHEN** refetch-images is started without a permalink target
|
||||
- **THEN** the command loads recent news items
|
||||
- **AND** enqueues at most 30 items ordered from newest to oldest
|
||||
|
||||
#### Scenario: Targeted permalink mode
|
||||
- **WHEN** refetch-images is started with a valid permalink target
|
||||
- **THEN** the command enqueues only the resolved article
|
||||
- **AND** bypasses latest-30 queue expansion
|
||||
|
||||
### Requirement: Sequential processing
|
||||
The image refetch queue SHALL be processed one item at a time.
|
||||
|
||||
|
||||
@@ -5,14 +5,29 @@ Canonical specification for responsive-device-agnostic-layout requirements synce
|
||||
## Requirements
|
||||
|
||||
### Requirement: Core layout is device-agnostic and responsive
|
||||
The system SHALL render key surfaces (header, hero, feed, modal, footer) responsively across mobile, tablet, and desktop viewports.
|
||||
The system SHALL render key surfaces (header, hero, feed, modal, footer, policy modals, and floating controls) responsively across mobile, tablet, and desktop viewports while preserving readability.
|
||||
|
||||
#### Scenario: Mobile layout behavior
|
||||
- **WHEN** a user opens the site on a mobile viewport
|
||||
- **THEN** content remains readable without horizontal overflow
|
||||
- **AND** interactive controls remain reachable and usable
|
||||
- **AND** interactive controls including icon-only copy/back-to-top and policy modals remain reachable and usable
|
||||
|
||||
#### Scenario: Desktop and tablet adaptation
|
||||
- **WHEN** a user opens the site on tablet or desktop viewports
|
||||
- **THEN** layout reflows according to breakpoint design rules
|
||||
- **AND** no key content or controls are clipped
|
||||
|
||||
#### Scenario: Readability-focused typography and contrast updates
|
||||
- **WHEN** content is rendered in core reading surfaces
|
||||
- **THEN** typography and color choices improve baseline readability
|
||||
- **AND** updates remain compatible with responsive behavior across breakpoints
|
||||
|
||||
#### Scenario: Sticky shrinking glass header
|
||||
- **WHEN** user scrolls downward
|
||||
- **THEN** header remains sticky with slight height reduction, subtle elevation, and glass blur effect
|
||||
- **AND** controls remain readable and usable at all breakpoints
|
||||
|
||||
#### Scenario: Sticky footer does not overlap core reading zones
|
||||
- **WHEN** footer is sticky
|
||||
- **THEN** content remains readable and interactive controls are not obscured
|
||||
- **AND** mobile/tablet/desktop layouts stay overflow-safe
|
||||
|
||||
21
openspec/specs/security-and-performance-test-harness/spec.md
Normal file
21
openspec/specs/security-and-performance-test-harness/spec.md
Normal file
@@ -0,0 +1,21 @@
|
||||
## Purpose
|
||||
|
||||
Canonical specification for security-and-performance-test-harness requirements synced from OpenSpec change deltas.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Security test harness runs in CI
|
||||
The system SHALL run baseline automated security checks in CI.
|
||||
|
||||
#### Scenario: Security checks execute
|
||||
- **WHEN** CI pipeline runs on protected branches
|
||||
- **THEN** dependency vulnerability and static security checks execute
|
||||
- **AND** high-severity findings fail the gate
|
||||
|
||||
### Requirement: Performance test harness enforces thresholds
|
||||
The system SHALL run page-speed and API-performance checks against defined thresholds.
|
||||
|
||||
#### Scenario: Performance regression detection
|
||||
- **WHEN** measured performance exceeds regression threshold
|
||||
- **THEN** performance gate fails
|
||||
- **AND** reports include metric deltas and failing surfaces
|
||||
@@ -17,6 +17,11 @@ The system SHALL expose standards-compliant SEO metadata on the homepage and pol
|
||||
- **THEN** the page includes page-specific `title` and `description` metadata
|
||||
- **AND** Open Graph and Twitter card metadata are present for link previews
|
||||
|
||||
#### Scenario: Homepage title remains stable and brand-oriented
|
||||
- **WHEN** homepage content updates to newer articles
|
||||
- **THEN** document title remains a stable brand title (for example `ClawFort AI News`)
|
||||
- **AND** title does not switch to latest-article headline text
|
||||
|
||||
### Requirement: Canonical and preview metadata remain deterministic
|
||||
The system SHALL keep canonical and preview metadata deterministic for each route to avoid conflicting crawler signals.
|
||||
|
||||
|
||||
47
openspec/specs/share-and-contact-microinteractions/spec.md
Normal file
47
openspec/specs/share-and-contact-microinteractions/spec.md
Normal file
@@ -0,0 +1,47 @@
|
||||
## Purpose
|
||||
|
||||
Canonical specification for share-and-contact-microinteractions requirements synced from OpenSpec change deltas.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Modal/footer exposes minimal icon-based share actions
|
||||
The system SHALL provide visible, accessible icon-only share actions for article permalinks on supported providers.
|
||||
|
||||
#### Scenario: Supported share providers
|
||||
- **WHEN** share controls are rendered
|
||||
- **THEN** icons for `X`, `WhatsApp`, and `LinkedIn` are displayed
|
||||
- **AND** activating an icon opens provider share flow with the article permalink
|
||||
|
||||
#### Scenario: Light-theme icon visibility
|
||||
- **WHEN** the site is in light mode
|
||||
- **THEN** share icons remain visibly distinguishable with accessible contrast
|
||||
- **AND** icon controls remain keyboard focusable
|
||||
|
||||
#### Scenario: Copy-link share action
|
||||
- **WHEN** a user activates the copy-to-clipboard share control
|
||||
- **THEN** the article permalink is written to clipboard
|
||||
- **AND** action succeeds without navigating away
|
||||
|
||||
### Requirement: Footer supports env-driven GitHub and contact links
|
||||
The system SHALL conditionally render GitHub and contact-email links from environment-backed configuration.
|
||||
|
||||
#### Scenario: Config present
|
||||
- **WHEN** GitHub URL and contact email are configured
|
||||
- **THEN** footer renders both links as interactive controls
|
||||
|
||||
#### Scenario: Config absent
|
||||
- **WHEN** either value is missing
|
||||
- **THEN** corresponding footer control is hidden without breaking layout
|
||||
|
||||
#### Scenario: Contact link visible when configured
|
||||
- **WHEN** `CONTACT_EMAIL` is present in frontend config payload
|
||||
- **THEN** footer shows the contact email affordance
|
||||
- **AND** hover microcopy behavior remains enabled
|
||||
|
||||
### Requirement: Contact affordance provides randomized safe microcopy
|
||||
The contact link SHALL present randomized, policy-safe helper messages to encourage feedback.
|
||||
|
||||
#### Scenario: Randomized helper tooltip
|
||||
- **WHEN** user hovers or nears the contact affordance
|
||||
- **THEN** a tooltip-style helper message is shown from a predefined safe message pool
|
||||
- **AND** message language avoids profanity/offensive/racist/sexist/misogynistic content
|
||||
@@ -27,3 +27,11 @@ Admin commands SHALL output actionable errors and final status summaries.
|
||||
- **WHEN** a maintenance command partially fails
|
||||
- **THEN** output includes succeeded/failed counts
|
||||
- **AND** includes actionable next-step guidance
|
||||
|
||||
### Requirement: Admin workflows have automated verification coverage
|
||||
Admin safety-critical workflows SHALL be covered by automated tests.
|
||||
|
||||
#### Scenario: Safety command regression test
|
||||
- **WHEN** admin command tests run in CI
|
||||
- **THEN** confirmation and dry-run behavior are validated by tests
|
||||
- **AND** regressions in safety guards fail the gate
|
||||
|
||||
@@ -11,11 +11,13 @@ The system SHALL emit Umami analytics events for summary modal open and close ac
|
||||
- **WHEN** a user opens the summary modal
|
||||
- **THEN** the system emits a modal-open Umami event
|
||||
- **AND** event payload includes article context identifier
|
||||
- **AND** event payload includes `article_title` when available
|
||||
|
||||
#### Scenario: Modal close event tagging
|
||||
- **WHEN** a user closes the summary modal
|
||||
- **THEN** the system emits a modal-close Umami event
|
||||
- **AND** event payload includes article context identifier when available
|
||||
- **AND** event payload includes `article_title` when available
|
||||
|
||||
### Requirement: Source link-out interactions are tagged for analytics
|
||||
The system SHALL emit Umami analytics events for source/citation link-outs from summary modal.
|
||||
|
||||
@@ -17,6 +17,10 @@ The system SHALL render article summary content in a modal dialog using the requ
|
||||
- **THEN** the modal is dismissed cleanly
|
||||
- **AND** user returns to previous feed context without page navigation
|
||||
|
||||
#### Scenario: Permalink-driven modal open
|
||||
- **WHEN** page is loaded with a valid article permalink state
|
||||
- **THEN** the modal opens for the linked article without requiring manual click
|
||||
|
||||
### Requirement: Modal content preserves source link-out behavior
|
||||
The system SHALL provide source link-outs from the summary modal.
|
||||
|
||||
@@ -24,3 +28,7 @@ The system SHALL provide source link-outs from the summary modal.
|
||||
- **WHEN** a user clicks source/citation link in the modal
|
||||
- **THEN** the original source opens in a new tab/window
|
||||
- **AND** modal behavior remains stable for continued browsing
|
||||
|
||||
#### Scenario: Modal exposes share entry points
|
||||
- **WHEN** a summary modal is open for an article
|
||||
- **THEN** share controls for the article permalink are available from modal/footer share area
|
||||
|
||||
@@ -5,14 +5,14 @@ Canonical specification for terms-of-use-risk-disclosure requirements synced fro
|
||||
## Requirements
|
||||
|
||||
### Requirement: Terms page states unverified-content risk
|
||||
The system SHALL provide a Terms of Use page that states information is unverified and use is at the user’s own risk.
|
||||
The system SHALL provide Terms of Use disclosure content that states information is unverified and use is at the user's own risk, including modal-based access from the landing experience.
|
||||
|
||||
#### Scenario: Terms page risk statement visible
|
||||
- **WHEN** a user opens the Terms of Use page
|
||||
- **THEN** the page includes clear at-own-risk usage language
|
||||
- **AND** the page states information is not independently verified
|
||||
#### Scenario: Terms disclosure risk statement visible
|
||||
- **WHEN** a user opens Terms of Use disclosure content from its supported entry points
|
||||
- **THEN** the content includes clear at-own-risk usage language
|
||||
- **AND** the content states information is not independently verified
|
||||
|
||||
#### Scenario: Terms page references source uncertainty
|
||||
- **WHEN** a user reads terms details
|
||||
- **THEN** the page explains content is surfaced from external/AI-generated sources
|
||||
#### Scenario: Terms disclosure references source uncertainty
|
||||
- **WHEN** a user reads Terms details
|
||||
- **THEN** the content explains information is surfaced from external/AI-generated sources
|
||||
- **AND** users are informed responsibility remains with their own decisions
|
||||
|
||||
26
openspec/specs/translation-quality-validation-gates/spec.md
Normal file
26
openspec/specs/translation-quality-validation-gates/spec.md
Normal file
@@ -0,0 +1,26 @@
|
||||
## Purpose
|
||||
|
||||
Canonical specification for translation-quality-validation-gates requirements synced from OpenSpec change deltas.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Translation output passes quality validation before use
|
||||
The system SHALL validate generated Tamil and Malayalam translation output for language/script sanity and gibberish risk before persistence or delivery.
|
||||
|
||||
#### Scenario: Valid translation accepted
|
||||
- **WHEN** generated translation passes configured language and quality checks
|
||||
- **THEN** the system stores and serves the translated content
|
||||
- **AND** records a successful validation outcome
|
||||
|
||||
#### Scenario: Invalid translation rejected
|
||||
- **WHEN** generated translation fails language/script or gibberish checks
|
||||
- **THEN** the system rejects translated output for that article-language pair
|
||||
- **AND** records a validation failure reason for operations visibility
|
||||
|
||||
### Requirement: Validation failure fallback is deterministic
|
||||
When translation quality validation fails, the system SHALL provide deterministic English fallback behavior.
|
||||
|
||||
#### Scenario: Failed translation falls back to English
|
||||
- **WHEN** a client requests language content for an article whose translation failed validation
|
||||
- **THEN** the system returns English source headline and summary
|
||||
- **AND** response shape remains consistent with language-aware responses
|
||||
@@ -5,14 +5,19 @@ Canonical specification for wcag-2-2-aa-accessibility requirements synced from O
|
||||
## Requirements
|
||||
|
||||
### Requirement: Core user flows comply with WCAG 2.2 AA baseline
|
||||
The system SHALL meet WCAG 2.2 AA accessibility requirements for primary interactions and content presentation.
|
||||
The system SHALL meet WCAG 2.2 AA accessibility requirements for primary interactions and content presentation, including icon-only controls and policy-disclosure modals, and SHALL verify compliance through automated accessibility checks in CI.
|
||||
|
||||
#### Scenario: Keyboard-only interaction flow
|
||||
- **WHEN** a keyboard-only user navigates the page
|
||||
- **WHEN** a keyboard-only user navigates policy modals and icon-only controls
|
||||
- **THEN** all primary interactive elements are reachable and operable
|
||||
- **AND** visible focus indication is present at each step
|
||||
|
||||
#### Scenario: Contrast and non-text alternatives
|
||||
- **WHEN** users consume text and non-text UI content
|
||||
- **THEN** color contrast meets AA thresholds for relevant text and controls
|
||||
- **AND** meaningful images and controls include accessible labels/alternatives
|
||||
- **AND** icon-only controls expose meaningful accessible labels
|
||||
|
||||
#### Scenario: Accessibility CI gate
|
||||
- **WHEN** pull request validation runs
|
||||
- **THEN** automated accessibility checks execute against key pages and flows
|
||||
- **AND** violations above configured severity fail the gate
|
||||
|
||||
Reference in New Issue
Block a user