Changes for page Requirements

Last modified by Robert Schaub on 2025/12/23 11:03

From 6.1 to 7.1

From version 1.1

edited by Robert Schaub
on 2025/12/22 19:12

Change comment: Imported from XAR

To version 6.1

edited by Robert Schaub
on 2025/12/23 08:03

Change comment: Imported from XAR

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -306,7 +306,7 @@
 . How common is this pattern?
 . Store in ErrorPattern table (improvement queue)
--=== 6.2 Weekly Improvement Cycle ===
++=== 6.2 Continuous Improvement Cycle ===
 . **Review**: Analyze top error patterns
 . **Develop**: Create fix (prompt, model, validation)
@@ -326,7 +326,7 @@
  * Re-work rate
  * Claims processed per hour
--**Goal**: 10% monthly improvement in error rate
++**Goal**: continuous improvement in error rate
  == 7. Automated Quality Monitoring ==
@@ -803,185 +803,405 @@
  === NFR12: Security Controls ===
--**Fulfills:** Production readiness, legal compliance
++**Fulfills:** Data protection, system integrity, user privacy, production readiness
--**Requirements:**
--1. **Input Validation:** SQL injection, XSS, CSRF prevention
--2. **Rate Limiting:** 5 analyses per minute per IP
--3. **Authentication:** Secure sessions, API key rotation
--4. **Data Protection:** HTTPS, encryption, backups
--5. **Security Audit:** Penetration testing, GDPR compliance
++**Phase:** Beta 0 (essential), V1.0 (complete) **BLOCKER**
--**Milestone:** Beta 0 (essential), V1.0 (complete) **BLOCKER**
++**Purpose:** Protect FactHarbor systems, user data, and operations from security threats, ensuring production-grade security posture.
++**Specification:**
++
++==== API Security ====
++
++**Rate Limiting:**
++* **Analysis endpoints:** 100 requests/hour per IP
++* **Read endpoints:** 1,000 requests/hour per IP
++* **Search:** 500 requests/hour per IP
++* **Authenticated users:** 5x higher limits
++* **Burst protection:** Max 10 requests/second
++
++**Authentication & Authorization:**
++* **API Keys:** Required for programmatic access
++* **JWT tokens:** For user sessions (1-hour expiry)
++* **OAuth2:** For third-party integrations
++* **Role-Based Access Control (RBAC):**
++  * Public: Read-only access to published claims
++  * Contributor: Submit claims, provide evidence
++  * Moderator: Review contributions, manage quality
++  * Admin: System configuration, user management
++
++**CORS Policies:**
++* Whitelist approved domains only
++* No wildcard origins in production
++* Credentials required for sensitive endpoints
++
++**Input Sanitization:**
++* Validate all user input against schemas
++* Sanitize HTML/JavaScript in text submissions
++* Prevent SQL injection (use parameterized queries)
++* Prevent command injection (no shell execution of user input)
++* Max request size: 10MB
++* File upload restrictions: Whitelist file types, scan for malware
++
++---
++
++==== Data Security ====
++
++**Encryption at Rest:**
++* Database encryption using AES-256
++* Encrypted backups
++* Key management via cloud provider KMS (AWS KMS, Google Cloud KMS)
++* Regular key rotation (90-day cycle)
++
++**Encryption in Transit:**
++* HTTPS/TLS 1.3 only (no TLS 1.0/1.1)
++* Strong cipher suites only
++* HSTS (HTTP Strict Transport Security) enabled
++* Certificate pinning for mobile apps
++
++**Secure Credential Storage:**
++* Passwords hashed with bcrypt (cost factor 12+)
++* API keys encrypted in database
++* Secrets stored in environment variables (never in code)
++* Use secrets manager (AWS Secrets Manager, HashiCorp Vault)
++
++**Data Privacy:**
++* Minimal data collection (privacy by design)
++* User data deletion on request (GDPR compliance)
++* PII encryption in database
++* Anonymize logs (no PII in log files)
++
++---
++
++==== Application Security ====
++
++**OWASP Top 10 Compliance:**
++
++1. **Broken Access Control:** RBAC implementation, path traversal prevention
++2. **Cryptographic Failures:** Strong encryption, secure key management
++3. **Injection:** Parameterized queries, input validation
++4. **Insecure Design:** Security review of all features
++5. **Security Misconfiguration:** Hardened defaults, security headers
++6. **Vulnerable Components:** Dependency scanning (see below)
++7. **Authentication Failures:** Strong password policy, MFA support
++8. **Data Integrity Failures:** Signature verification, checksums
++9. **Security Logging Failures:** Comprehensive audit logs
++10. **Server-Side Request Forgery:** URL validation, whitelist domains
++
++**Security Headers:**
++* `Content-Security-Policy`: Strict CSP to prevent XSS
++* `X-Frame-Options`: DENY (prevent clickjacking)
++* `X-Content-Type-Options`: nosniff
++* `Referrer-Policy`: strict-origin-when-cross-origin
++* `Permissions-Policy`: Restrict browser features
++
++**Dependency Vulnerability Scanning:**
++* **Tools:** Snyk, Dependabot, npm audit, pip-audit
++* **Frequency:** Daily automated scans
++* **Action:** Patch critical vulnerabilities within 24 hours
++* **Policy:** No known high/critical CVEs in production
++
++**Security Audits:**
++* **Internal:** Quarterly security reviews
++* **External:** Annual penetration testing by certified firm
++* **Bug Bounty:** Public bug bounty program (V1.1+)
++* **Compliance:** SOC 2 Type II certification target (V1.5)
++
++---
++
++==== Operational Security ====
++
++**DDoS Protection:**
++* CloudFlare or AWS Shield
++* Rate limiting at CDN layer
++* Automatic IP blocking for abuse patterns
++
++**Monitoring & Alerting:**
++* Real-time security event monitoring
++* Alerts for:
++  * Failed login attempts (>5 in 10 minutes)
++  * API abuse patterns
++  * Unusual data access patterns
++  * Security scan detections
++* Integration with SIEM (Security Information and Event Management)
++
++**Incident Response:**
++* Documented incident response plan
++* Security incident classification (P1-P4)
++* On-call rotation for security issues
++* Post-mortem for all security incidents
++* Public disclosure policy (coordinated disclosure)
++
++**Backup & Recovery:**
++* Daily encrypted backups
++* 30-day retention period
++* Tested recovery procedures (quarterly)
++* Disaster recovery plan (RTO: 4 hours, RPO: 1 hour)
++
++---
++
++==== Compliance & Standards ====
++
++**GDPR Compliance:**
++* User consent management
++* Right to access data
++* Right to deletion
++* Data portability
++* Privacy policy published
++
++**Accessibility:**
++* WCAG 2.1 AA compliance
++* Screen reader compatibility
++* Keyboard navigation
++* Alt text for images
++
++**Browser Support:**
++* Modern browsers only (Chrome/Edge/Firefox/Safari latest 2 versions)
++* No IE11 support
++
++**Acceptance Criteria:**
++
++* ✅ Passes OWASP ZAP security scan (no high/critical findings)
++* ✅ All dependencies with known vulnerabilities patched
++* ✅ Penetration test completed with no critical findings
++* ✅ Rate limiting blocks abuse attempts
++* ✅ Encryption at rest and in transit verified
++* ✅ Security headers scored A+ on securityheaders.com
++* ✅ Incident response plan documented and tested
++* ✅ 95% uptime over 30-day period
++
++
  === NFR13: Quality Metrics Transparency ===
--**Fulfills:** IFCN transparency, user trust
++**Fulfills:** User trust, transparency, continuous improvement, IFCN methodology transparency
--**Public Metrics:**
--* Quality gates performance
--* Evidence quality stats
--* Hallucination rate
--* User feedback
++**Phase:** POC2 (internal), Beta 0 (public), V1.0 (real-time)
--**Milestone:** POC2 (internal), Beta 0 (public), V1.0 (real-time)
++**Purpose:** Provide transparent, measurable quality metrics that demonstrate AKEL's performance and build user trust in automated fact-checking.
--== 10. Requirements Priority Matrix ==
++**Specification:**
--This table shows all functional and non-functional requirements ordered by urgency and priority.
++==== Component: Public Quality Dashboard ====
--**Note:** Implementation phases (POC1, POC2, Beta 0, V1.0) are defined in [[POC Requirements>>FactHarbor.Specification.POC.Requirements]] and [[Implementation Roadmap>>FactHarbor.Implementation-Roadmap.WebHome]], not in this priority matrix.
++**Core Metrics to Display:**
--**Priority Levels:**
--* **CRITICAL** - System doesn't work without it, or major safety/legal risk
--* **HIGH** - Core functionality, essential for success
--* **MEDIUM** - Important but not blocking
--* **LOW** - Nice to have, can be deferred
++**1. Verdict Quality Metrics**
--**Urgency Levels:**
--* **HIGH** - Immediate need (critical for proof of concept)
--* **MEDIUM** - Important but not immediate
--* **LOW** - Future enhancement
++**TIGERScore (Fact-Checking Quality):**
++* **Definition:** Measures how well generated verdicts match expert fact-checker judgments
++* **Scale:** 0-100 (higher is better)
++* **Calculation:** Using TIGERScore framework (Truth-conditional accuracy, Informativeness, Generality, Evaluativeness, Relevance)
++* **Target:** Average ≥80 for production release
++* **Display:**
++{{code}}
++Verdict Quality (TIGERScore):
++Overall: 84.2 ▲ (+2.1 from last month)
--|= ID |= Title |= Priority |= Urgency
--| **HIGH URGENCY** |||
--| **FR1** | Claim Intake | CRITICAL | HIGH
--| **FR5** | Evidence Collection | CRITICAL | HIGH
--| **FR7** | Verdict Computation | CRITICAL | HIGH
--| **NFR11** | Quality Assurance Framework | CRITICAL | HIGH
--| **FR2** | Claim Normalization | HIGH | HIGH
--| **FR3** | Claim Classification | HIGH | HIGH
--| **FR4** | Scenario Generation | HIGH | HIGH
--| **FR6** | Evidence Evaluation | HIGH | HIGH
--| **MEDIUM URGENCY** |||
--| **NFR12** | Security Controls | CRITICAL | MEDIUM
--| **FR9** | Corrections | HIGH | MEDIUM
--| **FR44** | ClaimReview Schema | HIGH | MEDIUM
--| **FR45** | Corrections Notification | HIGH | MEDIUM
--| **FR48** | Safety Framework | HIGH | MEDIUM
--| **NFR3** | Transparency | HIGH | MEDIUM
--| **NFR13** | Quality Metrics | HIGH | MEDIUM
--| **FR8** | User Contribution | MEDIUM | MEDIUM
--| **FR10** | Publishing | MEDIUM | MEDIUM
--| **FR13** | API | MEDIUM | MEDIUM
--| **FR46** | Image Verification | MEDIUM | MEDIUM
--| **FR47** | Archive.org Integration | MEDIUM | MEDIUM
--| **NFR1** | Performance | MEDIUM | MEDIUM
--| **NFR2** | Scalability | MEDIUM | MEDIUM
--| **NFR4** | Security & Privacy | MEDIUM | MEDIUM
--| **NFR5** | Maintainability | MEDIUM | MEDIUM
--| **LOW URGENCY** |||
--| **FR11** | Social Sharing | LOW | LOW
--| **FR12** | Notifications | LOW | LOW
--| **FR49** | A/B Testing | LOW | LOW
--| **FR50** | OSINT Toolkit Integration | LOW | LOW
--| **FR51** | Video Verification System | LOW | LOW
--| **FR52** | Interactive Detection Training | LOW | LOW
--| **FR53** | Cross-Organizational Sharing | LOW | LOW
++Distribution:
++  Excellent (>80): 67%
++  Good (60-80): 28%
++  Needs Improvement (<60): 5%
--**Total:** 31 requirements (23 Functional, 8 Non-Functional)
++Trend: [Graph showing improvement over time]
++{{/code}}
--**See also:**
--* [[POC Requirements>>FactHarbor.Specification.POC.Requirements]] - POC1 scope and simplifications
--* [[Implementation Roadmap>>FactHarbor.Implementation-Roadmap.WebHome]] - Phase-by-phase implementation plan
--* [[User Needs>>FactHarbor.Specification.Requirements.User Needs.WebHome]] - Foundation that drives these requirements
++**2. Hallucination & Faithfulness Metrics**
--=== 10.1 User Needs Priority ===
++**AlignScore (Faithfulness to Evidence):**
++* **Definition:** Measures how well verdicts align with actual evidence content
++* **Scale:** 0-1 (higher is better)
++* **Purpose:** Detect AI hallucinations (making claims not supported by evidence)
++* **Target:** Average ≥0.85, hallucination rate <5%
++* **Display:**
++{{code}}
++Evidence Faithfulness (AlignScore):
++Average: 0.87 ▼ (-0.02 from last month)
--User Needs (UN) are the foundation that drives functional and non-functional requirements. They are not independently prioritized; instead, their priority is inherited from the FR/NFR requirements they drive.
++Hallucination Rate: 4.2%
++  - Claims without evidence support: 3.1%
++  - Misrepresented evidence: 1.1%
--|= ID |= Title |= Drives Requirements
--| **UN-1** | Trust Assessment at a Glance | Multiple FR/NFR
--| **UN-2** | Claim Extraction and Verification | FR1-7
--| **UN-3** | Article Summary with FactHarbor Analysis Summary | FR4
--| **UN-4** | Social Media Fact-Checking | FR1, FR4
--| **UN-5** | Source Provenance and Track Records | FR6
--| **UN-6** | Publisher Reliability History | FR6
--| **UN-7** | Evidence Transparency | NFR3
--| **UN-8** | Understanding Disagreement and Consensus | FR4
--| **UN-9** | Methodology Transparency | NFR3, NFR11
--| **UN-10** | Manipulation Tactics Detection | FR48
--| **UN-11** | Filtered Research | FR3
--| **UN-12** | Submit Unchecked Claims | FR8
--| **UN-13** | Cite FactHarbor Verdicts | FR10
--| **UN-14** | API Access for Integration | FR13
--| **UN-15** | Verdict Evolution Timeline | FR7
--| **UN-16** | AI vs. Human Review Status | FR9
--| **UN-17** | In-Article Claim Highlighting | FR1
--| **UN-26** | Search Engine Visibility | FR44
--| **UN-27** | Visual Claim Verification | FR46
--| **UN-28** | Safe Contribution Environment | FR48
++Action: Prompt engineering review scheduled
++{{/code}}
--**Total:** 20 User Needs
++**3. Evidence Quality Metrics**
--**Note:** Each User Need inherits priority from the requirements it drives. For example, UN-2 (Claim Extraction and Verification) drives FR1-7, which are CRITICAL/HIGH priority, therefore UN-2 is also critical to the project.
++**Source Reliability:**
++* Average source quality score (0-1 scale)
++* Distribution of high/medium/low quality sources
++* Publisher track record trends
--== 11. MVP Scope ==
++**Evidence Coverage:**
++* Average number of sources per claim
++* Percentage of claims with ≥2 sources (EFCSN minimum)
++* Geographic diversity of sources
--**Phase 1 (Months 1-3): Read-Only MVP**
++**Display:**
++{{code}}
++Evidence Quality:
--Build:
--* Automated claim analysis
--* Confidence scoring
--* Source evaluation
--* Browse/search interface
--* User flagging system
++Average Sources per Claim: 4.2
++Claims with ≥2 sources: 94% (EFCSN compliant)
--**Goal**: Prove AI quality before adding user editing
++Source Quality Distribution:
++  High quality (>0.8): 48%
++  Medium quality (0.5-0.8): 43%
++  Low quality (<0.5): 9%
--**User Needs fulfilled in Phase 1**: UN-1, UN-2, UN-3, UN-4, UN-5, UN-6, UN-7, UN-8, UN-9, UN-12
++Geographic Diversity: 23 countries represented
++{{/code}}
--**Phase 2 (Months 4-6): User Contributions**
++**4. Contributor Consensus Metrics** (when human reviewers involved)
--Add only if needed:
--* Simple editing (Wikipedia-style)
--* Reputation system
--* Basic moderation
--* In-article claim highlighting (FR13)
++**Inter-Rater Reliability (IRR):**
++* **Calculation:** Cohen's Kappa or Fleiss' Kappa for multiple raters
++* **Scale:** 0-1 (higher is better)
++* **Interpretation:**
++  * >0.8: Almost perfect agreement
++  * 0.6-0.8: Substantial agreement
++  * 0.4-0.6: Moderate agreement
++  * <0.4: Poor agreement
++* **Target:** Maintain ≥0.7 (substantial agreement)
--**Additional User Needs fulfilled**: UN-13, UN-17
++**Display:**
++{{code}}
++Contributor Consensus:
--**Phase 3 (Months 7-12): Refinement**
++Inter-Rater Reliability (IRR): 0.73 (Substantial agreement)
++  - Verdict agreement: 78%
++  - Evidence quality agreement: 71%
++  - Scenario structure agreement: 69%
--* Continuous quality improvement
--* Feature additions based on real usage
--* Scale infrastructure
++Cases requiring moderator review: 12
++Moderator override rate: 8%
++{{/code}}
--**Additional User Needs fulfilled**: UN-14 (API access), UN-15 (Full evolution tracking)
++---
--**Deferred**:
--* Federation (until multiple successful instances exist)
--* Complex contribution workflows (focus on automation)
--* Extensive role hierarchy (keep simple)
++==== Quality Dashboard Implementation ====
--== 12. Success Metrics ==
++**Dashboard Location:** `/quality-metrics`
--**System Quality** (track weekly):
--* Error rate by category (target: -10%/month)
--* Average confidence score (target: increase)
--* Source quality distribution (target: more high-quality)
--* Contradiction detection rate (target: increase)
++**Update Frequency:**
++* **POC2:** Weekly manual updates
++* **Beta 0:** Daily automated updates
++* **V1.0:** Real-time metrics (updated hourly)
--**Efficiency** (track monthly):
--* Claims processed per hour (target: increase)
--* Human hours per claim (target: decrease)
--* Automation coverage (target: >90%)
--* Re-work rate (target: <5%)
++**Dashboard Sections:**
--**User Satisfaction** (track quarterly):
--* User flag rate (issues found)
--* Correction acceptance rate (flags valid)
--* Return user rate
--* Trust indicators (surveys)
++1. **Overview:** Key metrics at a glance
++2. **Verdict Quality:** TIGERScore trends and distributions
++3. **Evidence Analysis:** Source quality and coverage
++4. **AI Performance:** Hallucination rates, AlignScore
++5. **Human Oversight:** Contributor consensus, review rates
++6. **System Health:** Processing times, error rates, uptime
--**User Needs Metrics** (track quarterly):
--* UN-1: % users who understand trust scores
--* UN-4: Time to verify social media claim (target: <30s)
--* UN-7: % users who access evidence details
--* UN-8: % users who view multiple scenarios
--* UN-15: % users who check evolution timeline
--* UN-17: % users who enable in-article highlighting; avg. time spent on highlighted vs. non-highlighted articles
++**Example Dashboard Layout:**
++{{code}}
++┌─────────────────────────────────────────────────────────────┐
++│ FactHarbor Quality Metrics                    Last updated: │
++│ Public Dashboard                               2 hours ago   │
++└─────────────────────────────────────────────────────────────┘
++
++📊 KEY METRICS
++─────────────────────────────────────────────────────────────
++TIGERScore (Verdict Quality):        84.2 ▲ (+2.1)
++AlignScore (Faithfulness):            0.87 ▼ (-0.02)
++Hallucination Rate:                   4.2% ✓ (Target: <5%)
++Average Sources per Claim:            4.2  ▲ (+0.3)
++
++📈 TRENDS (30 days)
++─────────────────────────────────────────────────────────────
++[Graph: TIGERScore trending upward]
++[Graph: Hallucination rate declining]
++[Graph: Evidence quality stable]
++
++⚠️ IMPROVEMENT TARGETS
++─────────────────────────────────────────────────────────────
++1. Reduce hallucination rate to <3% (Current: 4.2%)
++2. Increase TIGERScore average to >85 (Current: 84.2)
++3. Maintain IRR >0.75 (Current: 0.73)
++
++📄 DETAILED REPORTS
++─────────────────────────────────────────────────────────────
++• Monthly Quality Report (PDF)
++• Methodology Documentation
++• AKEL Performance Analysis
++• Contributor Agreement Analysis
++
++{{/code}}
++
++---
++
++==== Continuous Improvement Feedback Loop ====
++
++**How Metrics Inform AKEL Improvements:**
++
++1. **Identify Weak Areas:**
++   * Low TIGERScore → Review prompt engineering
++   * High hallucination → Strengthen evidence grounding
++   * Low IRR → Clarify evaluation criteria
++
++2. **A/B Testing Integration:**
++   * Test prompt variations
++   * Measure impact on quality metrics
++   * Deploy winners automatically
++
++3. **Alert Thresholds:**
++   * TIGERScore drops below 75 → Alert team
++   * Hallucination rate exceeds 7% → Pause auto-publishing
++   * IRR below 0.6 → Moderator training needed
++
++4. **Monthly Quality Reviews:**
++   * Analyze trends
++   * Identify systematic issues
++   * Plan prompt improvements
++   * Update AKEL models
++
++---
++
++==== Metric Calculation Details ====
++
++**TIGERScore Implementation:**
++* Reference: https://github.com/TIGER-AI-Lab/TIGERScore
++* Input: Generated verdict + reference verdict (from expert)
++* Output: 0-100 score across 5 dimensions
++* Requires: Test set of expert-reviewed claims (minimum 100)
++
++**AlignScore Implementation:**
++* Reference: https://github.com/yuh-zha/AlignScore
++* Input: Generated verdict + source evidence text
++* Output: 0-1 faithfulness score
++* Calculation: Semantic alignment between claim and evidence
++
++**Source Quality Scoring:**
++* Use existing source reliability database (e.g., NewsGuard, MBFC)
++* Factor in: Publication history, corrections record, transparency
++* Scale: 0-1 (weighted average across sources)
++
++---
++
++==== Integration Points ====
++
++* **NFR11: AKEL Quality Assurance** - Metrics validate quality gate effectiveness
++* **FR49: A/B Testing** - Metrics measure test success
++* **FR11: Audit Trail** - Source of quality data
++* **NFR3: Transparency** - Public metrics build trust
++
++**Acceptance Criteria:**
++
++* ✅ All core metrics implemented and calculating correctly
++* ✅ Dashboard updates daily (Beta 0) or hourly (V1.0)
++* ✅ Alerts trigger when metrics degrade beyond thresholds
++* ✅ Monthly quality report auto-generates
++* ✅ Dashboard is publicly accessible (no login required)
++* ✅ Mobile-responsive dashboard design
++* ✅ Metrics inform quarterly AKEL improvement planning
++
++
++
++
  == 13. Requirements Traceability ==
  For full traceability matrix showing which requirements fulfill which user needs, see:
@@ -1014,39 +1014,387 @@
  === FR44: ClaimReview Schema Implementation ===
--Generate valid ClaimReview structured data for Google/Bing visibility.
++**Fulfills:** UN-13 (Cite FactHarbor Verdicts), UN-14 (API Access for Integration), UN-26 (Search Engine Visibility)
--**Schema.org Mapping:**
++**Phase:** V1.0
++
++**Purpose:** Generate valid ClaimReview structured data for every published analysis to enable Google/Bing search visibility and fact-check discovery.
++
++**Specification:**
++
++==== Component: Schema.org Markup Generator ====
++
++FactHarbor must generate valid ClaimReview structured data following Schema.org specifications for every published claim analysis.
++
++**Required JSON-LD Schema:**
++
++{{code language="json"}}
++{
++  "@context": "https://schema.org",
++  "@type": "ClaimReview",
++  "datePublished": "YYYY-MM-DD",
++  "url": "https://factharbor.org/claims/{claim_id}",
++  "claimReviewed": "The exact claim text",
++  "author": {
++    "@type": "Organization",
++    "name": "FactHarbor",
++    "url": "https://factharbor.org"
++  },
++  "reviewRating": {
++    "@type": "Rating",
++    "ratingValue": "1-5",
++    "bestRating": "5",
++    "worstRating": "1",
++    "alternateName": "FactHarbor likelihood score"
++  },
++  "itemReviewed": {
++    "@type": "Claim",
++    "author": {
++      "@type": "Person",
++      "name": "Claim author if known"
++    },
++    "datePublished": "YYYY-MM-DD if known",
++    "appearance": {
++      "@type": "CreativeWork",
++      "url": "Original claim URL if from article"
++    }
++  }
++}
++{{/code}}
++
++**FactHarbor-Specific Mapping:**
++
++**Likelihood Score to Rating Scale:**
  * 80-100% likelihood → 5 (Highly Supported)
--* 60-79% → 4 (Supported)
--* 40-59% → 3 (Mixed)
--* 20-39% → 2 (Questionable)
--* 0-19% → 1 (Refuted)
++* 60-79% likelihood → 4 (Supported)
++* 40-59% likelihood → 3 (Mixed/Uncertain)
++* 20-39% likelihood → 2 (Questionable)
++* 0-19% likelihood → 1 (Refuted)
--**Milestone:** V1.0
++**Multiple Scenarios Handling:**
++* If claim has multiple scenarios with different verdicts, generate **separate ClaimReview** for each scenario
++* Add `disambiguatingDescription` field explaining scenario context
++* Example: "Scenario: If interpreted as referring to 2023 data..."
++==== Implementation Requirements ====
++
++1. **Auto-generate** on claim publication
++2. **Embed** in HTML `<head>` section as JSON-LD script
++3. **Validate** against Schema.org validator before publishing
++4. **Submit** to Google Search Console for indexing
++5. **Update** automatically when verdict changes (integrate with FR8: Time Evolution)
++
++==== Integration Points ====
++
++* **FR7: Automated Verdicts** - Source of rating data and claim text
++* **FR8: Time Evolution** - Triggers schema updates when verdicts change
++* **FR11: Audit Trail** - Logs all schema generation and update events
++
++==== Resources ====
++
++* ClaimReview Project: https://www.claimreviewproject.com
++* Schema.org ClaimReview: https://schema.org/ClaimReview
++* Google Fact Check Guidelines: https://developers.google.com/search/docs/appearance/fact-check
++
++**Acceptance Criteria:**
++
++* ✅ Passes Google Structured Data Testing Tool
++* ✅ Appears in Google Fact Check Explorer within 48 hours of publication
++* ✅ Valid JSON-LD syntax (no errors)
++* ✅ All required fields populated with correct data types
++* ✅ Handles multi-scenario claims correctly (separate ClaimReview per scenario)
++
++
  === FR45: User Corrections Notification System ===
--Notify users when analyses are corrected.
++**Fulfills:** IFCN Principle 5 (Open & Honest Corrections), EFCSN compliance
--**Mechanisms:**
--1. In-page banner (30 days)
--2. Public correction log
--3. Email notifications (opt-in)
--4. RSS/API feed
++**Phase:** Beta 0 (basic), V1.0 (complete) **BLOCKER**
--**Milestone:** Beta 0 (basic), V1.0 (complete) **BLOCKER**
++**Purpose:** When any claim analysis is corrected, notify users who previously viewed the claim to maintain transparency and build trust.
++**Specification:**
++
++==== Component: Corrections Visibility Framework ====
++
++**Correction Types:**
++
++1. **Major Correction:** Verdict changes category (e.g., "Supported" → "Refuted")
++2. **Significant Correction:** Likelihood score changes >20%
++3. **Minor Correction:** Evidence additions, source quality updates
++4. **Scenario Addition:** New scenario added to existing claim
++
++==== Notification Mechanisms ====
++
++**1. In-Page Banner:**
++
++Display prominent banner on claim page:
++
++{{code}}
++[!] CORRECTION NOTICE
++This analysis was updated on [DATE]. [View what changed] [Dismiss]
++
++Major changes:
++• Verdict changed from "Likely True (75%)" to "Uncertain (45%)"
++• New contradicting evidence added from [Source]
++• Scenario 2 updated with additional context
++
++[See full correction log]
++{{/code}}
++
++**2. Correction Log Page:**
++
++* Public changelog at `/claims/{id}/corrections`
++* Displays for each correction:
++  * Date/time of correction
++  * What changed (before/after comparison)
++  * Why changed (reason if provided)
++  * Who made change (AKEL auto-update vs. contributor override)
++
++**3. Email Notifications (opt-in):**
++
++* Send to users who bookmarked or shared the claim
++* Subject: "FactHarbor Correction: [Claim title]"
++* Include summary of changes
++* Link to updated analysis
++
++**4. RSS/API Feed:**
++
++* Corrections feed at `/corrections.rss`
++* API endpoint: `GET /api/corrections?since={timestamp}`
++* Enables external monitoring by journalists and researchers
++
++==== Display Rules ====
++
++* Show banner on **ALL pages** displaying the claim (search results, related claims, embeddings)
++* Banner persists for **30 days** after correction
++* **"Corrections" count badge** on claim card
++* **Timestamp** on every verdict: "Last updated: [datetime]"
++
++==== IFCN Compliance Requirements ====
++
++* Corrections policy published at `/corrections-policy`
++* User can report suspected errors via `/report-error/{claim_id}`
++* Link to IFCN complaint process (if FactHarbor becomes signatory)
++* **Scrupulous transparency:** Never silently edit analyses
++
++==== Integration Points ====
++
++* **FR8: Time Evolution** - Triggers corrections when verdicts change
++* **FR11: Audit Trail** - Source of correction data and change history
++* **NFR3: Transparency** - Public correction log demonstrates commitment
++
++**Acceptance Criteria:**
++
++* ✅ Banner appears within 60 seconds of correction
++* ✅ Correction log is permanent and publicly accessible
++* ✅ Email notifications deliver within 5 minutes
++* ✅ RSS feed updates in real-time
++* ✅ Mobile-responsive banner design
++* ✅ Accessible (screen reader compatible)
++
++
  === FR46: Image Verification System ===
--**Methods:**
--1. Reverse image search
--2. EXIF metadata analysis
--3. Manipulation detection (basic)
--4. Context verification
++**Fulfills:** UN-27 (Visual Claim Verification)
--**Milestone:** Beta 0 (basic), V1.0 (extended)
++**Phase:** Beta 0 (basic), V1.0 (extended)
++**Purpose:** Verify authenticity and context of images shared with claims to detect manipulation, misattribution, and out-of-context usage.
++
++**Specification:**
++
++==== Component: Multi-Method Image Verification ====
++
++**Method 1: Reverse Image Search**
++
++**Purpose:** Find earlier uses of the image to verify context
++
++**Implementation:**
++* Integrate APIs:
++  * **Google Vision AI** (reverse search)
++  * **TinEye** (oldest known uses)
++  * **Bing Visual Search** (broad coverage)
++
++**Process:**
++1. Extract image from claim or user upload
++2. Query multiple reverse search services
++3. Analyze results for:
++   * Earliest known publication
++   * Original context (what was it really showing?)
++   * Publication timeline
++   * Geographic spread
++
++**Output:**
++{{code}}
++Reverse Image Search Results:
++
++Earliest known use: 2019-03-15 (5 years before claim)
++Original context: "Photo from 2019 flooding in Mumbai"
++This claim uses it for: "2024 hurricane damage in Florida"
++
++⚠️ Image is OUT OF CONTEXT
++
++Found in 47 other articles:
++• 2019-03-15: Mumbai floods (original)
++• 2020-07-22: Bangladesh monsoon
++• 2024-10-15: Current claim (misattributed)
++
++[View full timeline]
++{{/code}}
++
++---
++
++**Method 2: AI Manipulation Detection**
++
++**Purpose:** Detect deepfakes, face swaps, and digital alterations
++
++**Implementation:**
++* Integrate detection services:
++  * **Sensity AI** (deepfake detection)
++  * **Reality Defender** (multimodal analysis)
++  * **AWS Rekognition** (face detection inconsistencies)
++
++**Detection Categories:**
++1. **Face Manipulation:**
++   * Deepfake face swaps
++   * Expression manipulation
++   * Identity replacement
++
++2. **Image Manipulation:**
++   * Copy-paste artifacts
++   * Clone stamp detection
++   * Content-aware fill detection
++   * JPEG compression inconsistencies
++
++3. **AI Generation:**
++   * Detect fully AI-generated images
++   * Identify generation artifacts
++   * Check for model signatures
++
++**Confidence Scoring:**
++* **HIGH (80-100%):** Strong evidence of manipulation
++* **MEDIUM (50-79%):** Suspicious artifacts detected
++* **LOW (0-49%):** Minor inconsistencies or inconclusive
++
++**Output:**
++{{code}}
++Manipulation Analysis:
++
++Face Manipulation: LOW RISK (12%)
++Image Editing: MEDIUM RISK (64%)
++  • Clone stamp artifacts detected in sky region
++  • JPEG compression inconsistent between objects
++
++AI Generation: LOW RISK (8%)
++
++⚠️ Possible manipulation detected. Manual review recommended.
++{{/code}}
++
++---
++
++**Method 3: Metadata Analysis (EXIF)**
++
++**Purpose:** Extract technical details that may reveal manipulation or misattribution
++
++**Extracted Data:**
++* **Camera/Device:** Make, model, software
++* **Timestamps:** Original date, modification dates
++* **Location:** GPS coordinates (if present)
++* **Editing History:** Software used, edit count
++* **File Properties:** Resolution, compression, format conversions
++
++**Red Flags:**
++* Metadata completely stripped (suspicious)
++* Timestamp conflicts with claimed date
++* GPS location conflicts with claimed location
++* Multiple edit rounds (hiding something?)
++* Creation date after modification date (impossible)
++
++**Output:**
++{{code}}
++Image Metadata:
++
++Camera: iPhone 14 Pro
++Original date: 2023-08-12 14:32:15
++Location: 40.7128°N, 74.0060°W (New York City)
++Modified: 2024-10-15 08:45:22
++Software: Adobe Photoshop 2024
++
++⚠️ Location conflicts with claim
++Claim says: "Taken in Los Angeles"
++EXIF says: New York City
++
++⚠️ Edited 14 months after capture
++{{/code}}
++
++---
++
++==== Verification Workflow ====
++
++**Automatic Triggers:**
++1. User submits claim with image
++2. Article being analyzed contains images
++3. Social media post includes photos
++
++**Process:**
++1. Extract images from content
++2. Run all 3 verification methods in parallel
++3. Aggregate results into confidence score
++4. Generate human-readable summary
++5. Display prominently in analysis
++
++**Display Integration:**
++
++Show image verification panel in claim analysis:
++
++{{code}}
++📷 IMAGE VERIFICATION
++
++[Image thumbnail]
++
++✅ Reverse Search: Original context verified
++⚠️ Manipulation: Possible editing detected (64% confidence)
++✅ Metadata: Consistent with claim details
++
++Overall Assessment: CAUTION ADVISED
++This image may have been edited. Original context appears accurate.
++
++[View detailed analysis]
++{{/code}}
++
++==== Integration Points ====
++
++* **FR7: Automated Verdicts** - Image verification affects claim credibility
++* **FR4: Analysis Summary** - Image findings included in summary
++* **UN-27: Visual Claim Verification** - Direct fulfillment
++
++==== Cost Considerations ====
++
++**API Costs (estimated per image):**
++* Google Vision AI: $0.001-0.003
++* TinEye: $0.02 (commercial API)
++* Sensity AI: $0.05-0.10
++* AWS Rekognition: $0.001-0.002
++
++**Total per image:** ~$0.07-0.15
++
++**Mitigation Strategies:**
++* Cache results for duplicate images
++* Use free tier quotas where available
++* Prioritize higher-value claims for deep analysis
++* Offer premium verification as paid tier
++
++**Acceptance Criteria:**
++
++* ✅ Reverse image search finds original sources
++* ✅ Manipulation detection accuracy >80% on test dataset
++* ✅ EXIF extraction works for major image formats (JPEG, PNG, HEIC)
++* ✅ Results display within 10 seconds
++* ✅ Mobile-friendly image comparison interface
++* ✅ False positive rate <15%
++
++
  === FR47: Archive.org Integration ===
  Auto-save evidence sources to Wayback Machine.
@@ -1065,19 +1065,145 @@
  **Milestone:** V1.0
--=== FR50-FR53: Future Enhancements (V2.0+) ===
++=== FR50: OSINT Toolkit Integration ===
--* **FR50:** OSINT Toolkit Integration
--* **FR51:** Video Verification System
--* **FR52:** Interactive Detection Training
--* **FR53:** Cross-Organizational Sharing
--**Milestone:** V2.0+ (12-18 months post-launch)
--== Enhanced Existing Requirements ==
++**Fulfills:** Advanced media verification
++**Phase:** V1.1
--=== FR7: Automated Verdicts (Enhanced with Quality Gates) ===
++**Purpose:** Integrate open-source intelligence tools for advanced verification.
++**Tools to Integrate:**
++* InVID/WeVerify (video verification)
++* Bellingcat toolkit
++* Additional TBD based on V1.0 learnings
++
++=== FR51: Video Verification System ===
++
++
++
++**Fulfills:** UN-27 (Visual claims), advanced media verification
++**Phase:** V1.1
++
++**Purpose:** Verify video-based claims.
++
++**Specification:**
++* Keyframe extraction
++* Reverse video search
++* Deepfake detection (AI-powered)
++* Metadata analysis
++* Acoustic signature analysis
++
++=== FR52: Interactive Detection Training ===
++
++
++
++**Fulfills:** Media literacy education
++**Phase:** V1.5
++
++**Purpose:** Teach users to identify misinformation.
++
++**Specification:**
++* Interactive tutorials
++* Practice exercises
++* Detection quizzes
++* Gamification elements
++
++=== FR53: Cross-Organizational Sharing ===
++
++
++
++**Fulfills:** Collaboration with other fact-checkers
++**Phase:** V1.5
++
++**Purpose:** Share findings with IFCN/EFCSN members.
++
++**Specification:**
++* API for fact-checking organizations
++* Structured data exchange
++* Privacy controls
++* Attribution requirements
++
++
++== Summary ==
++
++**V1.0 Critical Requirements (Must Have):**
++
++* FR44: ClaimReview Schema ✅
++* FR45: Corrections Notification ✅
++* FR46: Image Verification ✅
++* FR47: Archive.org Integration ✅
++* FR48: Contributor Safety ✅
++* FR49: A/B Testing ✅
++* FR54: Evidence Deduplication ✅
++* NFR11: Quality Assurance Framework ✅
++* NFR12: Security Controls ✅
++* NFR13: Quality Metrics Dashboard ✅
++
++**V1.1+ (Future):**
++
++* FR50: OSINT Integration
++* FR51: Video Verification
++* FR52: Detection Training
++* FR53: Cross-Org Sharing
++
++
++**Total:** 11 critical requirements for V1.0
++
++=== FR54: Evidence Deduplication ===
++
++
++
++**Fulfills:** Accurate evidence counting, quality metrics
++**Phase:** POC2, Beta 0, V1.0
++
++**Purpose:** Avoid counting the same source multiple times when it appears in different forms.
++
++**Specification:**
++
++**Deduplication Logic:**
++
++1. **URL Normalization:**
++   * Remove tracking parameters (?utm_source=...)
++   * Normalize http/https
++   * Normalize www/non-www
++   * Handle redirects
++
++2. **Content Similarity:**
++   * If two sources have >90% text similarity → Same source
++   * If one is subset of other → Same source
++   * Use fuzzy matching for minor differences
++
++3. **Cross-Domain Syndication:**
++   * Detect wire service content (AP, Reuters)
++   * Mark as single source if syndicated
++   * Count original publication only
++
++**Display:**
++
++{{code}}
++Evidence Sources (3 unique, 5 total):
++
++1. Original Article (NYTimes)
++   - Also appeared in: WashPost, Guardian (syndicated)
++
++2. Research Paper (Nature)
++
++3. Official Statement (WHO)
++{{/code}}
++
++**Acceptance Criteria:**
++
++* ✅ URL normalization works
++* ✅ Content similarity detected
++* ✅ Syndicated content identified
++* ✅ Unique vs. total counts accurate
++* ✅ Improves evidence quality metrics
++
++
++== Additional Requirements (Lower Priority) ===== FR7: Automated Verdicts (Enhanced with Quality Gates) ===
++
  **POC1+ Enhancement:**
  After AKEL generates verdict, it passes through quality gates:

Changes for page Requirements

Summary

Details

Applications

Navigation

Need help?