First deployment
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-13
|
||||
@@ -0,0 +1,57 @@
|
||||
## Context
|
||||
|
||||
Current Umami event payloads for hero/feed CTA clicks and summary modal lifecycle events are identifier-heavy (`article_id`) and not directly human-readable in dashboards. Analysts must resolve IDs back to content to understand behavior patterns, which slows ad-hoc exploration and increases reporting friction.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Add `article_title` to existing CTA and summary modal analytics payloads.
|
||||
- Preserve existing event names and current fields for backward compatibility.
|
||||
- Keep changes scoped to frontend event payload construction.
|
||||
|
||||
**Non-Goals:**
|
||||
- Renaming event names or changing event timing semantics.
|
||||
- Introducing new analytics providers or backend event pipelines.
|
||||
- Reworking existing dashboard taxonomy outside payload enrichment.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Additive payload enrichment only
|
||||
**Choice:** Add `article_title` as an extra property while retaining `article_id` and existing metadata.
|
||||
|
||||
**Rationale:**
|
||||
- Backward compatible for existing analytics queries.
|
||||
- Immediate analyst readability improvement without migration burden.
|
||||
|
||||
### Decision 2: Use headline string from the in-memory item model
|
||||
**Choice:** Populate `article_title` from current article object (`item.headline` / `modalItem.headline`).
|
||||
|
||||
**Rationale:**
|
||||
- No extra network calls or state plumbing.
|
||||
- Data already present where events are emitted.
|
||||
|
||||
### Decision 3: Preserve event contracts and dispatch points
|
||||
**Choice:** Keep event names unchanged (`hero-cta-click`, `summary-modal-open`, `summary-modal-close`).
|
||||
|
||||
**Rationale:**
|
||||
- Avoids dashboard/query breakage.
|
||||
- Keeps this change low risk and auditable.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Risk] Long titles inflate payload size** -> Mitigation: send raw headline as-is; acceptable for low-volume client events.
|
||||
- **[Risk] Missing title on edge cases** -> Mitigation: include `article_id` as canonical fallback identifier.
|
||||
- **[Trade-off] Same event schema differs across historical windows** -> Mitigation: additive field keeps historical queries valid while enabling richer future segmentation.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Update event emitters in `frontend/index.html` to include `article_title`.
|
||||
2. Verify emitted payloads in browser devtools/Umami debug path.
|
||||
3. Update analytics-tagging spec deltas and task checklist.
|
||||
|
||||
Rollback:
|
||||
- Remove `article_title` field additions; existing events remain unchanged.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Do analysts also want `article_permalink` included now, or defer to future UX/permalink change?
|
||||
@@ -0,0 +1,23 @@
|
||||
## Why
|
||||
|
||||
Current Umami event payloads for CTA clicks and summary modal interactions include only `article_id`, which makes analysis harder when reviewing dashboards and raw events. Adding human-readable article context improves analyst speed and reduces lookup friction.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add `article_title` to CTA-click event payloads so click analytics can be understood without cross-referencing IDs.
|
||||
- Add `article_title` to summary modal open/close event payloads in addition to existing `article_id` context.
|
||||
- Keep existing event names and current fields intact for backward compatibility.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- None.
|
||||
|
||||
### Modified Capabilities
|
||||
- `hero-display`: Update analytics tracking requirement so CTA click events include both `article_id` and `article_title`.
|
||||
- `summary-analytics-tagging`: Update modal open/close analytics requirements so payload includes `article_title` with existing article context identifier.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Frontend analytics wiring:** `frontend/index.html` event payload construction for hero/feed CTA clicks and summary modal open/close events.
|
||||
- **Analytics consumers:** Umami dashboards and downstream event analysis gain readable article context while preserving existing identifiers.
|
||||
@@ -0,0 +1,21 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: News attribution display
|
||||
The system SHALL clearly attribute all news content and images to their sources.
|
||||
|
||||
#### Scenario: Source attribution
|
||||
- **WHEN** displaying any news item
|
||||
- **THEN** the system SHALL show the original source name and link
|
||||
- **AND** display image credit if available
|
||||
|
||||
#### Scenario: Perplexity attribution
|
||||
- **WHEN** displaying aggregated content
|
||||
- **THEN** the system SHALL include "Powered by Perplexity" in the footer
|
||||
|
||||
#### Scenario: Analytics tracking
|
||||
- **WHEN** Umami analytics is configured via `UMAMI_SCRIPT_URL` and `UMAMI_WEBSITE_ID`
|
||||
- **THEN** the system SHALL inject Umami tracking script into page head
|
||||
- **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
|
||||
@@ -0,0 +1,24 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Modal interactions are tagged for analytics
|
||||
The system SHALL emit Umami analytics events for summary modal open and close actions.
|
||||
|
||||
#### Scenario: Modal open event tagging
|
||||
- **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.
|
||||
|
||||
#### Scenario: Source link-out event tagging
|
||||
- **WHEN** a user clicks source/citation link in summary modal
|
||||
- **THEN** the system emits a link-out Umami event before or at navigation trigger
|
||||
- **AND** event includes source URL or source identifier metadata
|
||||
@@ -0,0 +1,15 @@
|
||||
## 1. Event Payload Enrichment
|
||||
|
||||
- [x] 1.1 Update hero/feed CTA tracking payloads in `frontend/index.html` to include `article_title` alongside `article_id`.
|
||||
- [x] 1.2 Update summary modal open tracking payload to include `article_title`.
|
||||
- [x] 1.3 Update summary modal close tracking payload to include `article_title` when available.
|
||||
|
||||
## 2. Compatibility and Safety
|
||||
|
||||
- [x] 2.1 Preserve existing event names (`hero-cta-click`, `summary-modal-open`, `summary-modal-close`) and existing fields.
|
||||
- [x] 2.2 Ensure payload enrichment is additive and does not break tracking when title is missing.
|
||||
|
||||
## 3. Validation
|
||||
|
||||
- [x] 3.1 Verify events in browser devtools/Umami network payload include `article_title`.
|
||||
- [x] 3.2 Verify existing dashboard queries based on `article_id` remain valid.
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-13
|
||||
@@ -0,0 +1,84 @@
|
||||
## Context
|
||||
|
||||
The current site works functionally but has usability gaps: dynamic homepage title behavior can confuse context, discovery/sharing of individual articles is weak, error pages are plain, and footer affordances are limited. Readability needs incremental tuning, especially for Tamil and Malayalam text rendering. These issues span frontend state management, metadata behavior, footer UX, and static asset/routing support.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Stabilize homepage title for clarity and SEO consistency.
|
||||
- Add back-to-top affordance and per-article permalink deep-linking that opens the correct modal.
|
||||
- Add minimal icon-based sharing (X/WhatsApp/LinkedIn) for modal/permalink flows.
|
||||
- Improve legibility via typography/color refinements, with explicit Tamil/Malayalam attention.
|
||||
- Introduce branded AI favicon.
|
||||
- Add expressive 404/500 pages with prominent code display and safe playful AI-style copy.
|
||||
- Add env-driven GitHub/email footer links with randomized safe feedback tooltip microcopy.
|
||||
|
||||
**Non-Goals:**
|
||||
- Rewriting router architecture or adding server-side rendering.
|
||||
- Adding complex social auth or third-party share SDKs.
|
||||
- Replacing existing analytics instrumentation.
|
||||
- Building full i18n content moderation pipeline for tooltip text.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Hash/query driven deep-link modal state
|
||||
**Choice:** Use permalink token (`?article=<id>` or hash equivalent) and resolve on load to open matching modal.
|
||||
|
||||
**Rationale:**
|
||||
- Works with existing SPA flow and avoids backend route explosion.
|
||||
- Easy to share/copy and easy to close by clearing URL state.
|
||||
|
||||
### Decision 2: Keep sharing implementation lightweight
|
||||
**Choice:** Construct provider share URLs client-side and use icon buttons without extra SDK dependencies.
|
||||
|
||||
**Rationale:**
|
||||
- Minimal bundle impact.
|
||||
- Predictable behavior with native share endpoints.
|
||||
|
||||
### Decision 3: Readability tuning via CSS tokens and language-aware classes
|
||||
**Choice:** Adjust text size/line-height/color contrast in existing theme token system; apply optional class hooks for Tamil/Malayalam content rendering.
|
||||
|
||||
**Rationale:**
|
||||
- Incremental and low-risk.
|
||||
- Preserves current theme architecture.
|
||||
|
||||
### Decision 4: Error pages with controlled safe message pool
|
||||
**Choice:** Use curated safe message templates (50+) and deterministic randomization per request/session.
|
||||
|
||||
**Rationale:**
|
||||
- “Oh no!” playful tone without unsafe generation risks.
|
||||
- No runtime LLM dependency required for error path.
|
||||
|
||||
### Decision 5: Footer extensibility via env-backed config
|
||||
**Choice:** Expose `GITHUB_REPO_URL` and `CONTACT_EMAIL` through existing frontend config bootstrap and render conditional links.
|
||||
|
||||
**Rationale:**
|
||||
- Keeps deployment-specific metadata configurable.
|
||||
- Avoids hardcoded personal links.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Risk] Deep-link to missing article id** -> Mitigation: fail gracefully (no modal open) and keep list view stable.
|
||||
- **[Risk] Tooltip microcopy quality drift** -> Mitigation: curate fixed safe message corpus and review before release.
|
||||
- **[Risk] Share URL encoding mistakes** -> Mitigation: centralized URL builder + encode all user-facing strings.
|
||||
- **[Trade-off] Stable homepage title reduces article-specific title SEO** -> Mitigation: keep OG/Twitter/article-level metadata contextual in card/modal/share surfaces.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Add permalink generation, URL parsing, and modal open-on-load logic.
|
||||
2. Add share icons/buttons and footer microinteraction links.
|
||||
3. Apply readability and color token tweaks; verify Tamil/Malayalam rendering.
|
||||
4. Add error page handlers/templates and safe message pool.
|
||||
5. Add favicon asset and head reference.
|
||||
6. Add env-config plumbing for GitHub/email footer links.
|
||||
|
||||
Rollback:
|
||||
- Revert permalink and share UI additions.
|
||||
- Revert title and readability token changes.
|
||||
- Restore prior generic error page behavior.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should permalink use numeric article id only, or slug+id hybrid for readability?
|
||||
- Should contact tooltip randomization rotate per hover event or per page load?
|
||||
- Should 404/500 messages be localized immediately or staged in English first?
|
||||
@@ -0,0 +1,36 @@
|
||||
## Why
|
||||
|
||||
Several small UX and content-discovery issues are adding friction across navigation, sharing, readability, and trust signals. Addressing them together delivers a noticeable quality jump with low implementation risk.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Set a stable homepage title (for example, `ClawFort AI News`) instead of changing it to the latest article headline.
|
||||
- Add a footer `Back to Top` action for quick navigation.
|
||||
- Add per-article permalinks and support deep-link behavior that opens the correct article modal on page load.
|
||||
- Add minimal icon-only share actions for permalink sharing (`X`, `WhatsApp`, `LinkedIn`) in modal/footer share area.
|
||||
- Improve readability with small typography/color updates, with extra attention to Tamil and Malayalam legibility.
|
||||
- Add custom 404/500 pages that prominently show the error code and include safe, playful AI-generated “Oh no!” style messages.
|
||||
- Add footer links driven by environment configuration for GitHub repo and contact email; include enhanced hover/near-cursor feedback messages from a randomized safe message pool.
|
||||
- Add an AI-themed favicon asset and wire it into the site.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `article-permalinks-and-deep-link-modal`: Defines canonical per-article permalink structure and modal auto-open behavior from URL state.
|
||||
- `share-and-contact-microinteractions`: Defines social share actions, configurable GitHub/email links, and randomized safe feedback microcopy for contact affordance.
|
||||
- `error-pages-with-playful-ai-messaging`: Defines 404/500 UX with prominent status codes and policy-safe AI-style messaging.
|
||||
- `site-branding-favicon`: Defines favicon asset requirements and integration.
|
||||
|
||||
### Modified Capabilities
|
||||
- `seo-meta-and-social-tags`: Update homepage title behavior to remain stable and brand-oriented while preserving metadata quality.
|
||||
- `summary-modal-experience`: Extend modal contract to support permalink-driven open state and share entry points.
|
||||
- `responsive-device-agnostic-layout`: Apply small typography/color refinements for readability across devices.
|
||||
- `language-aware-content-delivery`: Improve Tamil/Malayalam presentation quality in the existing delivery surfaces.
|
||||
- `footer-policy-links`: Extend footer navigation with back-to-top, GitHub, and contact affordances.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Frontend UI:** `frontend/index.html` (title policy, footer controls, permalink/deep-link modal behavior, share icons, readability tweaks, favicon link).
|
||||
- **Backend/Config:** environment variables for GitHub URL and contact email exposure; possible API/config exposure if frontend config bootstrapping is needed.
|
||||
- **Routing/Pages:** new error page templates/handlers for 404 and 500 responses.
|
||||
- **Content/UX:** curated safe message pool for contact tooltip/hover microcopy and error-page “Oh no!” messaging.
|
||||
@@ -0,0 +1,25 @@
|
||||
## ADDED 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.
|
||||
|
||||
#### 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: Invalid permalink fails safely
|
||||
- **WHEN** a permalink references a missing or invalid article identifier
|
||||
- **THEN** the page remains usable without hard failure
|
||||
- **AND** modal is not opened with incorrect content
|
||||
@@ -0,0 +1,20 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Error pages prominently display status code
|
||||
The system SHALL show prominent HTTP status code display on 404 and 500 pages.
|
||||
|
||||
#### Scenario: 404 rendering
|
||||
- **WHEN** user visits a non-existent route
|
||||
- **THEN** the page prominently displays `404`
|
||||
|
||||
#### Scenario: 500 rendering
|
||||
- **WHEN** an internal server error page is rendered
|
||||
- **THEN** the page prominently displays `500`
|
||||
|
||||
### Requirement: Error pages include safe playful AI-style messaging
|
||||
The system SHALL render an "Oh no!" style playful message that is safe and policy-compliant.
|
||||
|
||||
#### Scenario: Safe message selection
|
||||
- **WHEN** an error page is displayed
|
||||
- **THEN** a playful message is selected from a curated safe message set
|
||||
- **AND** message excludes profanity and discriminatory/abusive content
|
||||
@@ -0,0 +1,24 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Footer exposes policy navigation links
|
||||
The system SHALL display footer links for Terms of Use and Attribution on the landing page.
|
||||
|
||||
#### Scenario: Footer links visible on landing page
|
||||
- **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
|
||||
|
||||
#### 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 includes back-to-top action
|
||||
- **WHEN** a user reaches lower sections of the page
|
||||
- **THEN** footer exposes a "Back to Top" control
|
||||
- **AND** activating it returns viewport to page 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 links
|
||||
- **AND** absent values do not break footer layout
|
||||
@@ -0,0 +1,32 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: API supports language-aware content retrieval
|
||||
The system SHALL support language-aware content delivery for hero and feed reads using selected language input.
|
||||
|
||||
#### Scenario: Language-specific latest article response
|
||||
- **WHEN** a client requests latest article data with a supported language selection
|
||||
- **THEN** the system returns headline and summary in the selected language when available
|
||||
- **AND** includes the corresponding base article metadata and media attribution
|
||||
|
||||
#### Scenario: Language-specific paginated feed response
|
||||
- **WHEN** a client requests paginated feed data with a supported language selection
|
||||
- **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.
|
||||
|
||||
#### 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: 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
|
||||
- **AND** avoids breaking existing consumers of news endpoints
|
||||
@@ -0,0 +1,19 @@
|
||||
## MODIFIED 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.
|
||||
|
||||
#### 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
|
||||
|
||||
#### 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
|
||||
@@ -0,0 +1,19 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Core SEO metadata is present on public pages
|
||||
The system SHALL expose standards-compliant SEO metadata on the homepage and policy pages, including description, robots, canonical URL, and social preview metadata.
|
||||
|
||||
#### Scenario: Homepage metadata baseline exists
|
||||
- **WHEN** a crawler or browser loads the homepage
|
||||
- **THEN** the document includes `description`, `robots`, and canonical metadata
|
||||
- **AND** Open Graph and Twitter card metadata fields are present with non-empty values
|
||||
|
||||
#### Scenario: Policy pages include indexable metadata
|
||||
- **WHEN** a crawler loads `/terms` or `/attribution`
|
||||
- **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
|
||||
@@ -0,0 +1,28 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Modal/footer exposes minimal icon-based share actions
|
||||
The system SHALL provide icon-only social 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
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
@@ -0,0 +1,13 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Site includes AI-themed favicon
|
||||
The system SHALL include an AI-themed favicon asset and reference it from public pages.
|
||||
|
||||
#### Scenario: Favicon linked in document head
|
||||
- **WHEN** a public page is loaded
|
||||
- **THEN** a favicon link element resolves to the configured AI-themed icon asset
|
||||
|
||||
#### Scenario: Favicon asset is cacheable and valid
|
||||
- **WHEN** browser requests favicon asset
|
||||
- **THEN** asset responds successfully with a valid icon format
|
||||
- **AND** can be cached using standard static-asset policy
|
||||
@@ -0,0 +1,30 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Summary is rendered in a modal dialog using standard template
|
||||
The system SHALL render article summary content in a modal dialog using the required structure.
|
||||
|
||||
#### Scenario: Open summary modal
|
||||
- **WHEN** a user triggers summary view for an article
|
||||
- **THEN** a modal dialog opens and displays content in this order: relevant image, TL;DR bullets, summary body, source and citation, and "Powered by Perplexity"
|
||||
- **AND** modal content corresponds to the selected article
|
||||
|
||||
#### Scenario: Close summary modal
|
||||
- **WHEN** a user closes the modal via close control or backdrop interaction
|
||||
- **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.
|
||||
|
||||
#### Scenario: Source link-out from 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
|
||||
@@ -0,0 +1,41 @@
|
||||
## 1. Homepage Metadata and Navigation
|
||||
|
||||
- [x] 1.1 Set homepage title to stable brand title (e.g., `ClawFort AI News`) and prevent latest-article overrides.
|
||||
- [x] 1.2 Add footer `Back to Top` control with smooth scroll behavior.
|
||||
|
||||
## 2. Permalinks and Deep-Link Modal
|
||||
|
||||
- [x] 2.1 Add per-article permalink generation for hero and feed items.
|
||||
- [x] 2.2 Add URL parsing on load to detect permalink article target.
|
||||
- [x] 2.3 Open matching article modal automatically when permalink target is valid.
|
||||
- [x] 2.4 Handle invalid/missing permalink targets safely without UI breakage.
|
||||
|
||||
## 3. Sharing and Footer Contact UX
|
||||
|
||||
- [x] 3.1 Add icon-only share actions for `X`, `WhatsApp`, and `LinkedIn` using article permalinks.
|
||||
- [x] 3.2 Add env-driven footer GitHub link (`GITHUB_REPO_URL`) and contact email link (`CONTACT_EMAIL`).
|
||||
- [x] 3.3 Implement randomized safe tooltip microcopy pool (~50 messages) for contact affordance.
|
||||
|
||||
## 4. Readability Improvements
|
||||
|
||||
- [x] 4.1 Apply minor typography and color-contrast refinements across reading surfaces.
|
||||
- [x] 4.2 Add targeted Tamil/Malayalam readability tuning (font size/line-height/weight adjustments as needed).
|
||||
- [x] 4.3 Verify updates preserve responsive behavior across mobile/tablet/desktop.
|
||||
|
||||
## 5. Error Experience
|
||||
|
||||
- [x] 5.1 Implement custom 404 page with prominent status code and safe playful "Oh no!" message.
|
||||
- [x] 5.2 Implement custom 500 page with prominent status code and safe playful "Oh no!" message.
|
||||
- [x] 5.3 Add curated safe message set and deterministic/randomized selection strategy.
|
||||
|
||||
## 6. Branding Asset
|
||||
|
||||
- [x] 6.1 Add AI-themed favicon asset to static files with proper licensing/attribution notes if required.
|
||||
- [x] 6.2 Wire favicon reference in public page heads.
|
||||
|
||||
## 7. Validation
|
||||
|
||||
- [x] 7.1 Verify permalink deep-link opens correct modal and share links include correct URL.
|
||||
- [x] 7.2 Verify footer controls (policy links, back-to-top, GitHub, email) across breakpoints.
|
||||
- [x] 7.3 Verify Tamil/Malayalam readability changes in actual rendered content.
|
||||
- [x] 7.4 Verify 404/500 pages render status code + safe playful message.
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-13
|
||||
58
openspec/changes/archive/2026-02-13-p14-bugs/design.md
Normal file
58
openspec/changes/archive/2026-02-13-p14-bugs/design.md
Normal file
@@ -0,0 +1,58 @@
|
||||
## Context
|
||||
|
||||
Recent usability enhancements introduced regressions in modal consistency, footer/header behavior, and share/contact visibility. The issues are cross-cutting: SPA URL state, modal lifecycle handling, theme contrast, sticky surface behavior, and image relevance heuristics. The fixes must remain incremental and avoid feature re-architecture.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Restore modal parity for hero and feed deep links, including image loading and Escape-close behavior.
|
||||
- Ensure contact email is rendered when configured and share controls are visible in light mode.
|
||||
- Introduce copy-to-clipboard sharing and remove redundant card permalink affordance.
|
||||
- Implement floating Back-to-Top and compact sticky footer.
|
||||
- Implement sticky, shrinking, elevated glass header behavior on scroll.
|
||||
- Tighten image relevance fallback behavior for finance/market stories.
|
||||
|
||||
**Non-Goals:**
|
||||
- Full UI redesign.
|
||||
- New backend image provider integrations.
|
||||
- New analytics taxonomy.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Normalize deep-link modal resolution path
|
||||
Use one resolver for both hero and feed items, and open modal only after item context is guaranteed.
|
||||
|
||||
### Decision 2: Decouple modal close from item existence
|
||||
Escape and backdrop close should dismiss the modal even if modal item resolution is partially failed.
|
||||
|
||||
### Decision 3: Theme-safe icon tokens
|
||||
Share icon foreground/background tokens are split per theme to guarantee visibility in light mode.
|
||||
|
||||
### Decision 4: Sticky surfaces with conservative footprint
|
||||
Header remains sticky and shrinks slightly with blur/elevation on scroll; footer remains sticky with minimal height and readable contrast.
|
||||
|
||||
### Decision 5: Finance-aware image fallback guard
|
||||
If query contains market/finance intent, reject obviously unrelated animal/person close-up imagery via keyword guards and force finance-safe fallback query.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Risk] Sticky footer could occlude content** -> Mitigation: add bottom spacing to main content and reduce footer height.
|
||||
- **[Risk] Header animation jank on low-end devices** -> Mitigation: simple transform/opacity transitions only.
|
||||
- **[Risk] Stricter image relevance may reduce variety** -> Mitigation: constrain guardrails to high-confidence finance terms only.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Patch modal/deep-link lifecycle and close semantics in frontend state handlers.
|
||||
2. Patch share/contact visibility and add copy-link control.
|
||||
3. Implement sticky header/footer visual behavior.
|
||||
4. Patch image-query relevance guard in backend image selection.
|
||||
5. Validate with manual regression checklist.
|
||||
|
||||
Rollback:
|
||||
- Revert header/footer sticky behavior.
|
||||
- Revert modal resolver and share changes.
|
||||
- Revert image guardrails to prior fallback logic.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should copy-link action include transient toast feedback in this change or next UX pass?
|
||||
34
openspec/changes/archive/2026-02-13-p14-bugs/proposal.md
Normal file
34
openspec/changes/archive/2026-02-13-p14-bugs/proposal.md
Normal file
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
Several regressions and UX defects slipped in after recent enhancements, affecting modal behavior, sharing visibility, footer/header usability, and image relevance. Fixing these together will restore trust, readability, and navigation quality without introducing new product scope.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Fix permalink-to-hero modal behavior so image rendering and keyboard close (`Escape`) work consistently.
|
||||
- Restore footer contact email visibility and ensure env-driven contact link rendering is reliable.
|
||||
- Fix light-theme contrast for social share icons and add a copy-to-clipboard action alongside X, WhatsApp, and LinkedIn.
|
||||
- Replace inline footer "Back to Top" text button with a floating island-style control.
|
||||
- Make footer persistently sticky and compact while preserving reading comfort.
|
||||
- Make header persistently sticky with subtle shrink, elevation, and glass effect on scroll.
|
||||
- Tighten article-image relevance to avoid clearly unrelated images for finance/market stories.
|
||||
- Remove unnecessary per-card "Link" affordance from feed cards.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- None.
|
||||
|
||||
### Modified Capabilities
|
||||
- `article-permalinks-and-deep-link-modal`: Correct deep-link modal open-state parity for hero/feed targets and keyboard close behavior.
|
||||
- `share-and-contact-microinteractions`: Fix share-icon visibility in light mode, add copy-link action, and restore contact-email presence.
|
||||
- `footer-policy-links`: Update footer interaction model for sticky compact layout and floating back-to-top control.
|
||||
- `responsive-device-agnostic-layout`: Apply sticky header/footer behavior and ensure readability is not degraded.
|
||||
- `news-image-relevance-and-fallbacks`: Improve relevance guardrails to reduce obviously mismatched fallback/provider image outcomes.
|
||||
- `hero-display`: Remove redundant card-level permalink text affordance where it harms clarity.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Frontend UI:** `frontend/index.html` modal behaviors, keyboard handling, share controls, footer/header interactions, and card affordances.
|
||||
- **Backend config/data:** contact link exposure verification through `/config` payload and env handling.
|
||||
- **Image pipeline:** backend relevance and fallback heuristics in image selection paths.
|
||||
- **UX quality:** stronger consistency across themes and navigation paths, especially for permalink and sharing flows.
|
||||
@@ -0,0 +1,19 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### 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: 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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Footer exposes policy navigation links
|
||||
The system SHALL keep policy links while supporting sticky compact footer behavior and floating back-to-top control.
|
||||
|
||||
#### 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
|
||||
@@ -0,0 +1,16 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Infinite scroll news feed
|
||||
The system SHALL display feed cards without redundant per-card permalink text link when primary CTA and source link are present.
|
||||
|
||||
#### 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: Hero block display
|
||||
The system SHALL maintain hero-to-modal behavior parity with feed cards.
|
||||
|
||||
#### 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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Fallback behavior remains context-aware first
|
||||
The system SHALL apply stricter relevance guardrails before accepting summary images for finance/market stories.
|
||||
|
||||
#### 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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Core layout is device-agnostic and responsive
|
||||
The system SHALL preserve responsive readability while enabling sticky header and footer surfaces.
|
||||
|
||||
#### 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
|
||||
@@ -0,0 +1,22 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Modal/footer exposes minimal icon-based share actions
|
||||
The system SHALL provide visible, accessible icon-only share actions for article permalinks.
|
||||
|
||||
#### 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 render contact email link when `CONTACT_EMAIL` is configured.
|
||||
|
||||
#### 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
|
||||
30
openspec/changes/archive/2026-02-13-p14-bugs/tasks.md
Normal file
30
openspec/changes/archive/2026-02-13-p14-bugs/tasks.md
Normal file
@@ -0,0 +1,30 @@
|
||||
## 1. Permalink Modal Regression Fixes
|
||||
|
||||
- [x] 1.1 Fix deep-link modal open path for hero targets so modal structure and image loading match feed behavior.
|
||||
- [x] 1.2 Restore `Escape` close behavior for permalink-opened modal state.
|
||||
- [x] 1.3 Ensure invalid permalink handling does not break page interaction.
|
||||
|
||||
## 2. Share and Contact Fixes
|
||||
|
||||
- [x] 2.1 Fix light-mode social icon contrast tokens for X/WhatsApp/LinkedIn controls.
|
||||
- [x] 2.2 Add copy-to-clipboard share action for article permalink.
|
||||
- [x] 2.3 Restore footer contact email rendering from `/config` payload when `CONTACT_EMAIL` is set.
|
||||
|
||||
## 3. Header/Footer Usability Fixes
|
||||
|
||||
- [x] 3.1 Replace inline back-to-top text control with floating island control.
|
||||
- [x] 3.2 Make footer sticky and compact while preserving content readability.
|
||||
- [x] 3.3 Make header sticky with subtle shrink, elevation, and glass effect on scroll.
|
||||
|
||||
## 4. Content Relevance and Card Cleanup
|
||||
|
||||
- [x] 4.1 Add finance-story image relevance guardrails to avoid unrelated image classes.
|
||||
- [x] 4.2 Add finance-safe query retry/fallback refinement path.
|
||||
- [x] 4.3 Remove redundant card-level "Link" affordance from feed cards.
|
||||
|
||||
## 5. Verification
|
||||
|
||||
- [x] 5.1 Verify hero permalink opens modal with correct image and closing behavior.
|
||||
- [x] 5.2 Verify footer email presence and share icon visibility in light/dark themes.
|
||||
- [x] 5.3 Verify floating back-to-top, sticky footer, and sticky shrinking header on desktop/mobile.
|
||||
- [x] 5.4 Verify finance-story image relevance behavior and fallback safety.
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-13
|
||||
@@ -0,0 +1,55 @@
|
||||
## Context
|
||||
|
||||
The codebase has grown across frontend UX, backend ingestion, translations, analytics, and admin tooling. Quality checks are currently ad hoc and mostly manual, creating regression risk. A single cross-layer test and observability program is needed to enforce predictable release quality.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Establish CI quality gates covering unit, integration, E2E, accessibility, security, and performance.
|
||||
- Provide deterministic test fixtures for UI/API/DB workflows.
|
||||
- Define explicit coverage targets for critical paths and edge cases.
|
||||
- Add production monitoring and alerting for latency, failures, and freshness.
|
||||
|
||||
**Non-Goals:**
|
||||
- Migrating the app to a different framework.
|
||||
- Building a full SRE platform from scratch.
|
||||
- Replacing existing business logic outside remediation findings.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Layered test pyramid with release gates
|
||||
Adopt unit + integration + E2E layering; block release when any gate fails.
|
||||
|
||||
### Decision 2: Deterministic test data contracts
|
||||
Use seeded fixtures and mockable provider boundaries for repeatable results.
|
||||
|
||||
### Decision 3: Accessibility and speed as first-class CI checks
|
||||
Treat WCAG and page-speed regressions as gate failures with explicit thresholds.
|
||||
|
||||
### Decision 4: Security checks split by class
|
||||
Run dependency audit, static security lint, and API abuse smoke tests separately for clearer ownership.
|
||||
|
||||
### Decision 5: Monitoring linked to user-impacting SLOs
|
||||
Alert on API error rate, response latency, scheduler freshness, and failed fetch cycles.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Risk] Longer CI times** -> Mitigation: split fast/slow suites, parallelize jobs.
|
||||
- **[Risk] Flaky E2E tests** -> Mitigation: stable fixtures, retry policy only for known transient failures.
|
||||
- **[Risk] Alert fatigue** -> Mitigation: tune thresholds with burn-in period and severity levels.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Baseline current test/tooling and add missing framework dependencies.
|
||||
2. Implement layered suites and CI workflow stages.
|
||||
3. Add WCAG, speed, and security checks with thresholds.
|
||||
4. Add monitoring dashboards and alert routes.
|
||||
5. Run remediation sprint for failing gates.
|
||||
|
||||
Rollback:
|
||||
- Keep non-blocking mode for new gates until stability criteria are met.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Which minimum coverage threshold should be required for merge (line/branch)?
|
||||
- Which environments should execute full E2E and speed checks (PR vs nightly)?
|
||||
@@ -0,0 +1,36 @@
|
||||
## Why
|
||||
|
||||
The platform needs stronger quality gates to ensure stable, predictable behavior across releases. A complete testing and review program will reduce regressions, improve confidence in deployments, and surface performance, accessibility, and security risks earlier.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Introduce a unified automated test suite strategy covering unit, integration, and end-to-end paths.
|
||||
- Add end-to-end test coverage for core UI flows, API contracts, and database state transitions.
|
||||
- Add WCAG-focused accessibility checks and include them in quality gates.
|
||||
- Add page speed and runtime performance checks with repeatable thresholds.
|
||||
- Add baseline security testing (dependency, config, and common web vulnerability checks).
|
||||
- Add user-experience validation scenarios for key journeys and failure states.
|
||||
- Define comprehensive coverage expectations for critical features and edge cases.
|
||||
- Add a structured code-review/remediation/optimization pass to resolve quality debt.
|
||||
- Add performance monitoring and alerting requirements for production health visibility.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `platform-quality-gates`: Defines required CI quality gates and pass/fail criteria for release readiness.
|
||||
- `end-to-end-system-testing`: Defines end-to-end testing coverage across UI, API, and database workflows.
|
||||
- `security-and-performance-test-harness`: Defines security checks and page/runtime performance testing strategy.
|
||||
- `observability-monitoring-and-alerting`: Defines performance monitoring signals, dashboards, and alerting thresholds.
|
||||
- `code-review-remediation-workflow`: Defines structured remediation and optimization workflow after comprehensive review.
|
||||
|
||||
### Modified Capabilities
|
||||
- `wcag-2-2-aa-accessibility`: Expand verification requirements to include automated accessibility testing in release gates.
|
||||
- `delivery-and-rendering-performance`: Add enforceable page speed benchmarks and regression thresholds.
|
||||
- `site-admin-safety-and-ergonomics`: Add operational verification requirements tied to maintenance command behaviors.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Testing/Tooling:** New test suites, fixtures, and CI workflows for UI/API/DB/accessibility/security/performance.
|
||||
- **Frontend/Backend:** Potential bug fixes and optimizations discovered during comprehensive test and review passes.
|
||||
- **Operations:** Monitoring/alerting setup and documentation for performance and reliability signals.
|
||||
- **Release Process:** Stronger quality gates before archive/release actions.
|
||||
@@ -0,0 +1,17 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Comprehensive review findings are tracked and remediated
|
||||
The system SHALL track review findings and remediation outcomes in a structured workflow.
|
||||
|
||||
#### Scenario: Review finding lifecycle
|
||||
- **WHEN** a code review identifies defect, risk, or optimization opportunity
|
||||
- **THEN** finding is recorded with severity/owner/status
|
||||
- **AND** remediation is linked to a verifiable change
|
||||
|
||||
### Requirement: Optimization work is bounded and measurable
|
||||
Optimization actions SHALL include measurable before/after evidence.
|
||||
|
||||
#### Scenario: Optimization evidence recorded
|
||||
- **WHEN** performance or code quality optimization is implemented
|
||||
- **THEN** benchmark or metric delta is documented
|
||||
- **AND** no functional regression is introduced
|
||||
@@ -0,0 +1,43 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: HTTP delivery applies compression and cache policy
|
||||
The system SHALL apply transport-level compression and explicit cache directives for static assets, API responses, and public HTML routes.
|
||||
|
||||
#### Scenario: Compressed responses are available for eligible payloads
|
||||
- **WHEN** a client requests compressible content that exceeds the compression threshold
|
||||
- **THEN** the response is served with gzip compression
|
||||
- **AND** response headers advertise the selected content encoding
|
||||
|
||||
#### Scenario: Route classes receive deterministic cache-control directives
|
||||
- **WHEN** clients request static assets, API responses, or HTML page routes
|
||||
- **THEN** each route class returns a cache policy aligned to its freshness requirements
|
||||
- **AND** cache directives are explicit and testable from response headers
|
||||
|
||||
### Requirement: Media rendering optimizes perceived loading performance
|
||||
The system SHALL lazy-load non-critical images and render shimmer placeholders until image load completion or fallback resolution.
|
||||
|
||||
#### Scenario: Feed and modal images lazy-load with placeholders
|
||||
- **WHEN** feed or modal images have not completed loading
|
||||
- **THEN** a shimmer placeholder is visible for the pending image region
|
||||
- **AND** the placeholder is removed after load or fallback error handling completes
|
||||
|
||||
#### Scenario: Image rendering reduces layout shift risk
|
||||
- **WHEN** article images are rendered in hero, feed, or modal contexts
|
||||
- **THEN** image elements include explicit dimensions and async decoding hints
|
||||
- **AND** layout remains stable while content loads
|
||||
|
||||
### Requirement: Smooth scrolling behavior is consistently enabled
|
||||
The system SHALL provide smooth scrolling behavior for in-page navigation and user-initiated scroll interactions.
|
||||
|
||||
#### Scenario: In-page navigation uses smooth scrolling
|
||||
- **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
|
||||
@@ -0,0 +1,16 @@
|
||||
## ADDED 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
|
||||
@@ -0,0 +1,16 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Production monitoring covers key reliability signals
|
||||
The system SHALL capture and expose reliability/performance metrics for core services.
|
||||
|
||||
#### Scenario: Metrics available for operations
|
||||
- **WHEN** production system is running
|
||||
- **THEN** dashboards expose API latency/error rate, scheduler freshness, and ingestion health signals
|
||||
|
||||
### Requirement: Alerting is actionable and threshold-based
|
||||
The system SHALL send alerts on defined thresholds with clear operator guidance.
|
||||
|
||||
#### Scenario: Threshold breach alert
|
||||
- **WHEN** a monitored metric breaches configured threshold
|
||||
- **THEN** alert is emitted to configured channel
|
||||
- **AND** alert includes service, metric, threshold, and suggested next action
|
||||
@@ -0,0 +1,17 @@
|
||||
## ADDED 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
|
||||
@@ -0,0 +1,17 @@
|
||||
## ADDED 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
|
||||
@@ -0,0 +1,33 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Confirmation guard for destructive commands
|
||||
Destructive admin commands SHALL require explicit confirmation before execution.
|
||||
|
||||
#### Scenario: Missing confirmation flag
|
||||
- **WHEN** an operator runs clear-news or clean-archive without required confirmation
|
||||
- **THEN** the command exits without applying destructive changes
|
||||
- **AND** prints guidance for explicit confirmation usage
|
||||
|
||||
### Requirement: Dry-run support where applicable
|
||||
Maintenance commands SHALL provide dry-run mode for previewing effects where feasible.
|
||||
|
||||
#### Scenario: Dry-run preview
|
||||
- **WHEN** an operator invokes a command with dry-run mode
|
||||
- **THEN** the command reports intended actions and affected counts
|
||||
- **AND** persists no data changes
|
||||
|
||||
### Requirement: Actionable failure summaries
|
||||
Admin commands SHALL output actionable errors and final status summaries.
|
||||
|
||||
#### Scenario: Partial failure reporting
|
||||
- **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
|
||||
@@ -0,0 +1,19 @@
|
||||
## MODIFIED 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, and SHALL verify compliance through automated accessibility checks in CI.
|
||||
|
||||
#### Scenario: Keyboard-only interaction flow
|
||||
- **WHEN** a keyboard-only user navigates the page
|
||||
- **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
|
||||
|
||||
#### 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
|
||||
@@ -0,0 +1,43 @@
|
||||
## 1. Test Framework Baseline
|
||||
|
||||
- [x] 1.1 Inventory current test/tooling gaps across frontend, backend, and DB layers.
|
||||
- [x] 1.2 Add or standardize test runners, fixtures, and deterministic seed data.
|
||||
- [x] 1.3 Define CI quality-gate stages and failure policies.
|
||||
|
||||
## 2. UI/API/DB End-to-End Coverage
|
||||
|
||||
- [x] 2.1 Implement E2E tests for critical UI journeys (hero/feed/modal/permalink/share).
|
||||
- [x] 2.2 Implement API contract integration tests for news, config, and admin flows.
|
||||
- [x] 2.3 Add DB state verification for ingestion, archiving, and translation workflows.
|
||||
- [x] 2.4 Add edge-case E2E scenarios for invalid input, empty data, and failure paths.
|
||||
|
||||
## 3. Accessibility and UX Testing
|
||||
|
||||
- [x] 3.1 Integrate automated WCAG checks into CI for core pages.
|
||||
- [x] 3.2 Add keyboard-focus and contrast regression checks.
|
||||
- [x] 3.3 Add user-experience validation checklist for readability and interaction clarity.
|
||||
|
||||
## 4. Security and Performance Testing
|
||||
|
||||
- [x] 4.1 Add dependency and static security scanning to CI.
|
||||
- [x] 4.2 Add abuse/safety smoke tests for API endpoints.
|
||||
- [x] 4.3 Add page-speed and runtime performance checks with threshold budgets.
|
||||
- [x] 4.4 Fail pipeline when security/performance thresholds are breached.
|
||||
|
||||
## 5. Review, Remediation, and Optimization
|
||||
|
||||
- [x] 5.1 Run comprehensive code review pass and log findings with severity/owner.
|
||||
- [x] 5.2 Remediate defects uncovered by automated and manual testing.
|
||||
- [x] 5.3 Implement optimization tasks with before/after evidence.
|
||||
|
||||
## 6. Monitoring and Alerting
|
||||
|
||||
- [x] 6.1 Define production metrics for reliability and latency.
|
||||
- [x] 6.2 Configure dashboards and alert thresholds for key services.
|
||||
- [x] 6.3 Add alert runbook guidance for common incidents.
|
||||
|
||||
## 7. Final Validation
|
||||
|
||||
- [x] 7.1 Verify all quality gates pass in CI.
|
||||
- [x] 7.2 Verify coverage targets and edge-case suites meet defined thresholds.
|
||||
- [x] 7.3 Verify monitoring alerts trigger correctly in test conditions.
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-13
|
||||
100
openspec/changes/archive/2026-02-13-p16-more-bugs/design.md
Normal file
100
openspec/changes/archive/2026-02-13-p16-more-bugs/design.md
Normal file
@@ -0,0 +1,100 @@
|
||||
## Context
|
||||
|
||||
This change addresses unresolved regressions introduced by recent UX and content pipeline updates. The affected areas cross frontend interaction patterns (`frontend/index.html`), policy content delivery (`backend/main.py`), translation generation (`backend/news_service.py`), and admin image maintenance operations (`backend/cli.py`). Current behavior still allows low-quality translations and repeated or weakly related refetched images, and policy links still rely on full-page navigation.
|
||||
|
||||
Key constraints:
|
||||
- Maintain existing OpenSpec capability contracts where possible and ship mostly as requirement deltas.
|
||||
- Preserve permalink identity for machine/admin targeting, while removing redundant user-facing permalink chrome on hero.
|
||||
- Keep deterministic fallback behavior (AI-themed image fallback and English fallback for failed translations).
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Deliver modal-based Terms and Attribution access with keyboard-safe behavior.
|
||||
- Remove visible hero permalink affordance while preserving internal permalink targeting.
|
||||
- Improve Tamil/Malayalam hero readability on desktop and mobile.
|
||||
- Switch copy and back-to-top controls to icon-first interaction while preserving accessibility labels.
|
||||
- Add translation quality validation gates (wrong-language/gibberish rejection and deterministic fallback).
|
||||
- Extend refetch-images to support permalink targeting and enforce alternative relevant image selection (non-repeat, relevance/safety filters, AI fallback when uncertain).
|
||||
|
||||
**Non-Goals:**
|
||||
- Replacing the existing rendering framework or routing model.
|
||||
- Introducing new external image providers in this change.
|
||||
- Reworking full article ingestion architecture beyond targeted translation/image guardrails.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Policy disclosure moves to modal-first UI with deep-link-safe state
|
||||
Use in-page modals for Terms and Attribution content while supporting deterministic open/close state from URL params or equivalent state synchronization.
|
||||
|
||||
Alternatives considered:
|
||||
- Keep route pages only: rejected due to UX friction and context switch from main feed.
|
||||
- Embed truncated inline footer text: rejected due to disclosure readability and legal clarity risks.
|
||||
|
||||
### Decision 2: Hero permalink identity remains internal, not a primary visual affordance
|
||||
Retain permalink generation/parsing helpers for deep links and admin targeting, but remove visible hero permalink action from hero chrome.
|
||||
|
||||
Alternatives considered:
|
||||
- Remove permalink behavior entirely: rejected because admin targeting and deep-link tooling need stable identifiers.
|
||||
- Keep visible permalink: rejected because current hero action density and readability are degraded.
|
||||
|
||||
### Decision 3: Locale-aware hero readability profile for Tamil/Malayalam
|
||||
Apply stronger readability guardrails for non-English hero text: increased contrast treatment, safer line-wrapping, language-specific typography tuning.
|
||||
|
||||
Alternatives considered:
|
||||
- Single style for all languages: rejected; longer glyph clusters and script density degrade legibility.
|
||||
- Separate locale-specific templates: rejected as too heavy for this stabilization change.
|
||||
|
||||
### Decision 4: Icon-only controls must remain explicitly accessible
|
||||
Use icon-based copy and back-to-top controls with accessible names, keyboard operation, and stable tap targets.
|
||||
|
||||
Alternatives considered:
|
||||
- Text-only controls: rejected by updated UX requirement.
|
||||
- Icon-only without explicit labels: rejected due to WCAG and discoverability concerns.
|
||||
|
||||
### Decision 5: Translation quality gate before persistence/serving
|
||||
Add post-generation validation for expected language/script sanity and basic gibberish detection. If validation fails, mark translation unavailable and serve deterministic English fallback.
|
||||
|
||||
Alternatives considered:
|
||||
- Blindly accept model output: rejected due to current wrong-language/gibberish incidents.
|
||||
- Human moderation for all translations: rejected for runtime latency and operational overhead.
|
||||
|
||||
### Decision 6: Refetch image selection becomes candidate-based and non-repeat
|
||||
For refetch operations, generate contextual query candidates, filter against relevance/safety constraints, reject current/previously used image matches for the same article, and fall back to AI-themed image when confidence is low or candidates are exhausted.
|
||||
|
||||
Alternatives considered:
|
||||
- First-provider-first-image approach: rejected because it often repeats or returns weakly related imagery.
|
||||
- Hard blocklist only: rejected; insufficient for relevance and dedupe guarantees.
|
||||
|
||||
### Decision 7: Admin refetch supports permalink-targeted execution
|
||||
Extend admin command contract to accept a permalink input, resolve to article identity, and run the same queue/refetch pipeline with targeted scope.
|
||||
|
||||
Alternatives considered:
|
||||
- Keep limit-based batch-only refetch: rejected; operators need deterministic single-article correction path.
|
||||
- Add separate ad hoc script: rejected due to fragmented operational surface.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Risk] Modal policy flow may regress keyboard/focus behavior** -> Mitigation: explicit focus trap, escape-close, and focus-return requirements.
|
||||
- **[Risk] Translation validation may over-reject valid short outputs** -> Mitigation: bounded heuristic thresholds plus deterministic English fallback and logging for tuning.
|
||||
- **[Risk] Stronger image filtering can reduce image diversity** -> Mitigation: multi-candidate ranking and fallback to AI-themed image instead of unrelated imagery.
|
||||
- **[Risk] Permalink-targeted admin flow may fail on malformed or stale links** -> Mitigation: strict permalink parser and clear operator error summaries.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Introduce modal policy behavior and hero/readability/icon control updates in frontend.
|
||||
2. Add translation quality gate logic and fallback outcomes in backend translation path.
|
||||
3. Extend image refetch pipeline with candidate ranking, dedupe, relevance/safety filters, and fallback.
|
||||
4. Add permalink-targeted admin refetch argument and resolution path.
|
||||
5. Validate through existing/manual verification paths and update OpenSpec tasks.
|
||||
|
||||
Rollback:
|
||||
- Revert p16 frontend modal/icon/readability changes.
|
||||
- Revert translation gate checks to prior translation acceptance path.
|
||||
- Revert permalink-targeted and dedupe-aware refetch logic to prior batch refetch behavior.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should policy modals update canonical URL state (`?modal=terms`) for shareable deep links, or stay ephemeral-only?
|
||||
- What minimum confidence/sanity threshold should trigger translation rejection for short headlines?
|
||||
- Should image dedupe history persist only per article current/previous image, or maintain wider history window?
|
||||
@@ -0,0 +1,46 @@
|
||||
## Why
|
||||
|
||||
Recent UX and content-quality updates still leave several user-facing regressions unresolved across policy access, hero readability, share/back-to-top controls, translation quality, and image refetch behavior. These issues directly affect trust and usability, so we need a focused stabilization change that tightens both frontend interactions and backend content-quality guardrails.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Convert Terms of Use and Attribution access from full-page navigation to in-page modal dialogs while preserving clear disclosure content and keyboard accessibility.
|
||||
- Remove hero-level permalink affordance from visible hero chrome.
|
||||
- Improve hero readability for non-English content (Tamil/Malayalam) across desktop and mobile.
|
||||
- Replace text-based copy/share and back-to-top controls with icon-based controls that remain accessible.
|
||||
- Add translation quality validation to reduce wrong-language or gibberish outputs before serving/storing translated content.
|
||||
- Upgrade `admin refetch-images` behavior so refreshed images are alternative (not same as current), subject-relevant, and filtered against unrelated animal/pet outcomes.
|
||||
- Extend admin image refetch operations to accept a permalink target and fetch a new relevant image for that article.
|
||||
- Keep deterministic AI-themed fallback behavior when confidence is low or relevance checks fail.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `policy-disclosure-modals`: In-page modal experience for Terms of Use and Attribution content (focus trap, escape close, deep-link-safe modal state).
|
||||
- `translation-quality-validation-gates`: Post-translation validation gates (language/script sanity + gibberish rejection + deterministic fallback policy).
|
||||
- `permalink-targeted-image-refetch`: Admin command support for refetching summary images by permalink target.
|
||||
- `alternative-image-selection-and-dedupe`: Refetch pipeline guarantees alternative image selection, relevance scoring, repeat-image avoidance, and unsafe/unrelated-image filtering.
|
||||
|
||||
### Modified Capabilities
|
||||
- `footer-policy-links`: Footer policy access behavior changes from route navigation emphasis to modal activation flow.
|
||||
- `terms-of-use-risk-disclosure`: Terms content remains required, but delivery surface changes from standalone page-centric flow to modal-capable flow.
|
||||
- `attribution-disclaimer-page`: Attribution content remains required, but delivery surface changes from standalone page-centric flow to modal-capable flow.
|
||||
- `hero-display`: Hero chrome removes visible permalink affordance and preserves clean primary/secondary actions.
|
||||
- `hero-summary-entry-and-readability`: Strengthen multilingual hero readability requirements, especially for Tamil/Malayalam headline and summary rendering.
|
||||
- `responsive-device-agnostic-layout`: Ensure icon-based controls and modal policy surfaces remain usable and unclipped on mobile/tablet/desktop.
|
||||
- `wcag-2-2-aa-accessibility`: Icon-only controls and policy modals require explicit accessible labels, keyboard navigation, and focus behavior.
|
||||
- `article-translations-ml-tm`: Add quality validation outcomes for generated Tamil/Malayalam translations before persistence/serving.
|
||||
- `language-aware-content-delivery`: Define deterministic fallback behavior when requested translation fails quality validation.
|
||||
- `admin-maintenance-command-suite`: Extend admin command contract to include permalink-targeted image refetch execution path.
|
||||
- `queued-image-refetch-with-backoff`: Extend queue behavior to support targeted permalink jobs and non-repeat image outcomes.
|
||||
- `context-aware-image-selection-recovery`: Improve subject extraction and keyword recovery for alternative relevant image retrieval.
|
||||
- `news-image-relevance-and-fallbacks`: Tighten relevance/safety checks to reject unrelated animal/pet imagery and preserve AI-themed fallback when uncertain.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Frontend/UI**: `frontend/index.html` policy-link behavior, hero metadata/actions, icon controls, modal state handling, and locale-specific readability styles.
|
||||
- **Backend API/Routes**: `backend/main.py` policy content delivery strategy and compatibility with modal-first access.
|
||||
- **Admin CLI**: `backend/cli.py` image refetch command arguments and permalink-targeted workflow.
|
||||
- **Image pipeline**: `backend/news_service.py` subject extraction, alternative image candidate selection, dedupe/repeat prevention, relevance/safety filtering, and fallback selection.
|
||||
- **Translation pipeline**: `backend/news_service.py` translation response validation and fallback policy; potential metadata persistence updates in repository/model layers.
|
||||
- **Operational behavior**: Additional logging/audit fields for translation-quality failures and image-refetch decision path to support debugging and trust.
|
||||
@@ -0,0 +1,9 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Unified admin command surface
|
||||
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
|
||||
@@ -0,0 +1,25 @@
|
||||
## ADDED 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,19 @@
|
||||
## MODIFIED 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 and validate translation quality before persistence.
|
||||
|
||||
#### Scenario: Translation generation for new article
|
||||
- **WHEN** a new source article is accepted for storage
|
||||
- **THEN** the system requests Tamil and Malayalam translations for headline and summary
|
||||
- **AND** translation generation occurs in the same ingestion flow for that article
|
||||
|
||||
#### Scenario: Translation failure fallback
|
||||
- **WHEN** translation generation fails for one or both target languages
|
||||
- **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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Attribution page discloses AI generation and non-ownership
|
||||
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 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 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
|
||||
@@ -0,0 +1,17 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Context-aware image query generation
|
||||
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 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 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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Footer exposes policy navigation links
|
||||
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.
|
||||
|
||||
#### Scenario: Footer policy controls visible and focusable
|
||||
- **WHEN** a user loads the main page
|
||||
- **THEN** the footer includes controls labeled "Terms of Use" and "Attribution"
|
||||
- **AND** controls are visually distinguishable and keyboard focusable
|
||||
|
||||
#### 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
|
||||
@@ -0,0 +1,9 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Hero block display
|
||||
The system SHALL display hero article actions without a visible permalink affordance while preserving primary summary and source attribution interactions.
|
||||
|
||||
#### 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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### 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, 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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Language fallback to English is deterministic
|
||||
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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Fallback behavior remains context-aware first
|
||||
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 candidate evaluation fails
|
||||
|
||||
#### 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
|
||||
@@ -0,0 +1,14 @@
|
||||
## ADDED 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
|
||||
@@ -0,0 +1,27 @@
|
||||
## ADDED 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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Latest-30 queue construction
|
||||
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 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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Core layout is device-agnostic and responsive
|
||||
The system SHALL render key surfaces (header, hero, feed, modal, footer, policy modals, and floating controls) responsively across mobile, tablet, and desktop viewports.
|
||||
|
||||
#### Scenario: Mobile layout behavior
|
||||
- **WHEN** a user opens the site on a mobile viewport
|
||||
- **THEN** content remains readable without horizontal overflow
|
||||
- **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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Terms page states unverified-content 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 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 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
|
||||
@@ -0,0 +1,22 @@
|
||||
## ADDED 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
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED 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, including icon-only controls and policy-disclosure modals.
|
||||
|
||||
#### Scenario: Keyboard-only interaction flow
|
||||
- **WHEN** a keyboard-only user navigates policy modals and icon-only controls
|
||||
- **THEN** all primary interactive elements remain 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** icon-only controls expose meaningful accessible labels
|
||||
43
openspec/changes/archive/2026-02-13-p16-more-bugs/tasks.md
Normal file
43
openspec/changes/archive/2026-02-13-p16-more-bugs/tasks.md
Normal file
@@ -0,0 +1,43 @@
|
||||
## 1. Policy Disclosure Modal Conversion
|
||||
|
||||
- [x] 1.1 Implement Terms of Use modal surface and wire footer control to open it in-page.
|
||||
- [x] 1.2 Implement Attribution modal surface and wire footer control to open it in-page.
|
||||
- [x] 1.3 Add modal focus trap, Escape-close, and focus-return behavior for policy dialogs.
|
||||
- [x] 1.4 Ensure policy modal state handling is deep-link-safe and does not break existing navigation.
|
||||
|
||||
## 2. Hero and Interaction Chrome Cleanup
|
||||
|
||||
- [x] 2.1 Remove visible hero permalink affordance while preserving hero summary and source actions.
|
||||
- [x] 2.2 Replace modal copy-link text control with icon-only button and accessible labels.
|
||||
- [x] 2.3 Replace floating back-to-top text control with icon-only button and accessible labels.
|
||||
|
||||
## 3. Multilingual Hero Readability Hardening
|
||||
|
||||
- [x] 3.1 Improve Tamil/Malayalam hero headline and summary readability across desktop and mobile.
|
||||
- [x] 3.2 Tune hero overlay/contrast behavior to preserve legibility over bright image regions.
|
||||
- [x] 3.3 Verify no clipping/overlap regressions in hero metadata and controls on narrow viewports.
|
||||
|
||||
## 4. Translation Quality Validation Gates
|
||||
|
||||
- [x] 4.1 Add translation quality validation checks for language/script sanity and gibberish rejection.
|
||||
- [x] 4.2 Persist/log translation validation outcomes for observability and debugging.
|
||||
- [x] 4.3 Enforce deterministic English fallback when requested translation fails validation.
|
||||
- [x] 4.4 Prevent invalid translation variants from being served as authoritative localized content.
|
||||
|
||||
## 5. Refetch Image Quality and Targeting Enhancements
|
||||
|
||||
- [x] 5.1 Extend admin refetch-images to accept permalink-targeted execution.
|
||||
- [x] 5.2 Resolve permalink targets to article identity with actionable operator error output.
|
||||
- [x] 5.3 Implement candidate-based refetch selection that prefers subject-relevant alternatives.
|
||||
- [x] 5.4 Reject duplicate current-image outcomes for same-article refetch operations.
|
||||
- [x] 5.5 Reject clearly unrelated animal/pet imagery during candidate filtering.
|
||||
- [x] 5.6 Preserve deterministic AI-themed fallback when no acceptable candidate exists.
|
||||
- [x] 5.7 Emit progress/decision-path output for targeted and batch refetch execution.
|
||||
|
||||
## 6. Verification
|
||||
|
||||
- [x] 6.1 Verify Terms and Attribution open as accessible modals from footer controls.
|
||||
- [x] 6.2 Verify hero permalink affordance is removed and core hero actions still function.
|
||||
- [x] 6.3 Verify Tamil/Malayalam hero readability on desktop and mobile.
|
||||
- [x] 6.4 Verify translation-quality gate fallback behavior for wrong-language/gibberish outputs.
|
||||
- [x] 6.5 Verify permalink-targeted refetch returns alternative relevant image and avoids pet-style mismatches.
|
||||
Reference in New Issue
Block a user