First deployment
This commit is contained in:
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?
|
||||
@@ -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,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,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