Changes for page Requirements

Last modified by Robert Schaub on 2025/12/24 20:34

From 1.1 to 2.1 From 8.3 to 8.4

From version 2.1

edited by Robert Schaub
on 2025/12/12 09:32

Change comment: Imported from XAR

To version 8.3

edited by Robert Schaub
on 2025/12/16 20:27

Change comment: Update document after refactoring.

Raw
Rendered

Summary

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

Details

Page properties

Parent

@@ -1,1 +1,1 @@
--FactHarbor.Specification.WebHome
++FactHarbor.Archive.FactHarbor V0\.9\.18.Specification.WebHome

Content

@@ -1,91 +1,643 @@
  = Requirements =
--This chapter defines the requirements for FactHarbor.
++This page defines **Roles**, **Responsibilities**, and **Rules** for contributors and users of FactHarbor.
--== User Roles ==
++== Roles ==
  === Reader ===
--* **Responsibilities**: Browse, search, view scenarios/verdicts, flag issues.
--* **Permissions**: Read-only access.
--* **Limitations**: Cannot change content.
++**Who**: Anyone (no login required).
++
++**Can**:
++* Browse and search claims
++* View scenarios, evidence, verdicts, and timelines
++* Compare scenarios and explore assumptions
++* Flag issues, errors, contradictions, or suspicious patterns
++* Use filters, search, and visualization tools
++* Create personal views (saved searches, bookmarks - local browser storage)
++* **Submit claims automatically** by providing text to analyze - new claims are added automatically unless equal claims already exist in the system
++
++**Cannot**:
++* Modify existing content
++* Access draft content
++* Participate in governance decisions
++
++**Note**: Readers can request human review of AI-generated content by flagging it.
++
  === Contributor ===
--* **Responsibilities**: Submit claims, draft scenarios, attach evidence.
--* **Permissions**: Create/Edit drafts, comment.
--* **Limitations**: Cannot publish without review.
++**Who**: Registered and logged-in users (extends Reader capabilities).
++
++**Can**:
++* Everything a Reader can do
++* Submit claims
++* Submit evidence
++* Provide feedback
++* Suggest scenarios
++* Flag content for review
++* Request human review of AI-generated content
++
++**Cannot**:
++* Publish or mark content as "reviewed" or "approved"
++* Override expert or maintainer decisions
++* Directly modify AKEL or quality gate configurations
++
  === Reviewer ===
--* **Responsibilities**: Validate contributions, check consistency.
--* **Permissions**: Change status to "Published" or "Rejected".
--=== Expert ===
--* **Responsibilities**: Domain-specific judgment, refine assumptions.
--* **Permissions**: Attach expert annotations, propose re-evaluation.
++**Who**: Trusted community members, appointed by maintainers.
++**Can**:
++* Review contributions from Contributors and AKEL drafts
++* Validate AI-generated content (Mode 2 → Mode 3 transition)
++* Edit claims, scenarios, and evidence
++* Add clarifications or warnings
++* Change content status: `draft` → `in review` → `published` / `rejected`
++* Approve or reject **Tier B and C** content for "Human-Reviewed" status
++* Flag content for expert review
++* Participate in audit sampling
++
++**Cannot**:
++* Approve Tier A content for "Human-Reviewed" status (requires Expert)
++* Change governance rules
++* Unilaterally change expert conclusions without process
++* Bypass quality gates
++
++**Note on AI-Drafted Content**:
++* Reviewers can validate AI-generated content (Mode 2) to promote it to "Human-Reviewed" (Mode 3)
++* For Tier B and C, Reviewers have approval authority
++* For Tier A, only Experts can grant "Human-Reviewed" status
++
++=== Expert (Domain-Specific) ===
++
++**Who**: Subject-matter specialists in specific domains (medicine, law, science, etc.).
++
++**Can**:
++* Everything a Reviewer can do
++* **Final authority** on Tier A content "Human-Reviewed" status
++* Validate complex or controversial claims in their domain
++* Define domain-specific quality standards
++* Set reliability thresholds for domain sources
++* Participate in risk tier assignment review
++* Override AKEL suggestions in their domain (with documentation)
++
++**Cannot**:
++* Change platform governance policies
++* Approve content outside their expertise domain
++* Bypass technical quality gates (but can flag for adjustment)
++
++**Specialization**:
++* Experts are domain-specific (e.g., "Medical Expert", "Legal Expert", "Climate Science Expert")
++* Cross-domain claims may require multiple expert reviews
++
++=== Auditor ===
++
++**Who**: Reviewers or Experts assigned to sampling audit duties.
++
++**Can**:
++* Review sampled AI-generated content against quality standards
++* Validate quality gate enforcement
++* Identify patterns in AI errors or hallucinations
++* Provide feedback for system improvement
++* Flag content for immediate review if errors found
++* Contribute to audit statistics and transparency reports
++
++**Cannot**:
++* Change audit sampling algorithms (maintainer responsibility)
++* Bypass normal review workflows
++* Audit content they personally created
++
++**Selection**:
++* Auditors selected based on domain expertise and review quality
++* Rotation to prevent audit fatigue
++* Stratified assignment (Tier A auditors need higher expertise)
++
++**Audit Focus**:
++* Tier A: Recommendation 30-50% sampling rate, expert auditors
++* Tier B: Recommendation 10-20% sampling rate, reviewer/expert auditors
++* Tier C: Recommendation 5-10% sampling rate, reviewer auditors
++
  === Moderator ===
--* **Responsibilities**: Handle abuse, spam, and manipulation.
--* **Permissions**: Hide content, ban users.
--=== Maintainer / Administrator ===
--* **Responsibilities**: Node config, security, role assignment.
--* **Permissions**: System configuration.
++**Who**: Maintainers or trusted long-term contributors.
--=== AKEL (AI) ===
--* **Responsibilities**: Propose drafts, normalize, classify.
--* **Permissions**: Create machine-generated drafts.
--* **Limitations**: Never publishes without human approval.
++**Can**:
++* All Reviewer and Expert capabilities (cross-domain)
++* Manage user accounts and permissions
++* Handle disputes and conflicts
++* Enforce community guidelines
++* Suspend or ban abusive users
++* Finalize publication status for sensitive content
++* Review and adjust risk tier assignments
++* Oversee audit system performance
--== Functional Requirements ==
++**Cannot**:
++* Change core data model or architecture
++* Override technical system constraints
++* Make unilateral governance decisions without consensus
--=== Claim Intake & Normalization ===
--* **FR1**: Support text, URL, document input.
--* **FR2**: Normalize wording while preserving original.
--* **FR3**: Classify by domain/type.
--* **FR4**: Cluster similar claims.
++=== Maintainer ===
--=== Scenario System ===
--* **FR5**: Create scenarios linked to clusters.
--* **FR6**: Require Definitions, Assumptions, Boundaries.
--* **FR7**: Full versioning.
--* **FR8**: Side-by-side comparison.
++**Who**: Core team members responsible for the platform.
--=== Evidence Management ===
--* **FR9**: Ingest external sources.
--* **FR10**: Assess reliability/quality.
--* **FR11**: Link evidence to multiple scenarios.
++**Can**:
++* All Moderator capabilities
++* Change data model, architecture, and technical systems
++* Configure quality gates and AKEL parameters
++* Adjust audit sampling algorithms
++* Set and modify risk tier policies
++* Make platform-wide governance decisions
++* Access and modify backend systems
++* Deploy updates and fixes
++* Grant and revoke roles
--=== Verdicts & Truth Landscape ===
--* **FR12**: Likelihood-based verdicts **per scenario**.
--* **FR13**: Aggregate into Truth Landscape.
--* **FR14**: Show evolution over time.
++**Governance**:
++* Maintainers operate under organizational governance rules
++* Major policy changes require Governing Team approval
++* Technical decisions made collaboratively
--=== Workflow & Audit ===
--* **FR15**: Draft -> Review -> Publish states.
--* **FR16**: Moderation tools.
--* **FR17**: Full audit trail.
++----
++== Content Publication States ==
++
++=== Mode 1: Draft ===
++* Not visible to public
++* Visible to contributor and reviewers
++* Can be edited by contributor or reviewers
++* Default state for failed quality gates
++
++=== Mode 2: AI-Generated (Published) ===
++* **Public** and visible to all users
++* Clearly labeled as "AI-Generated, Awaiting Human Review"
++* Passed all automated quality gates
++* Risk tier displayed (A/B/C)
++* Users can:
++  ** Read and use content
++  ** Request human review
++  ** Flag for expert attention
++* Subject to sampling audits
++* Can be promoted to Mode 3 by reviewer/expert validation
++
++=== Mode 3: Human-Reviewed (Published) ===
++* **Public** and visible to all users
++* Labeled as "Human-Reviewed" with reviewer/expert attribution
++* Passed quality gates + human validation
++* Highest trust level
++* For Tier A, requires Expert approval
++* For Tier B/C, Reviewer approval sufficient
++
++=== Rejected ===
++* Not visible to public
++* Visible to contributor with rejection reason
++* Can be resubmitted after addressing issues
++* Rejection logged for transparency
++
++----
++
++== Contribution Rules ==
++
++=== All Contributors Must: ===
++* Provide sources for claims
++* Use clear, neutral language
++* Avoid personal attacks or insults
++* Respect intellectual property (cite sources)
++* Accept community feedback gracefully
++
++=== AKEL (AI) Must: ===
++* Mark all outputs with `AuthorType = AI`
++* Pass quality gates before Mode 2 publication
++* Perform mandatory contradiction search
++* Disclose confidence levels and uncertainty
++* Provide traceable reasoning chains
++* Flag potential bubbles or echo chambers
++* Submit to audit sampling
++
++=== Reviewers Must: ===
++* Be impartial and evidence-based
++* Document reasoning for decisions
++* Escalate to experts when appropriate
++* Participate in audits when assigned
++* Provide constructive feedback
++
++=== Experts Must: ===
++* Stay within domain expertise
++* Disclose conflicts of interest
++* Document specialized terminology
++* Provide reasoning for domain-specific decisions
++* Participate in Tier A audits
++
++----
++
++== Quality Standards ==
++
++=== Source Requirements ===
++* Primary sources preferred over secondary
++* Publication date and author must be identifiable
++* Sources must be accessible (not paywalled when possible)
++* Contradictory sources must be acknowledged
++* Echo chamber sources must be flagged
++
++=== Claim Requirements ===
++* Falsifiable or evaluable
++* Clear definitions of key terms
++* Boundaries and scope stated
++* Assumptions made explicit
++* Uncertainty acknowledged
++
++=== Evidence Requirements ===
++* Relevant to the claim and scenario
++* Reliability assessment provided
++* Methodology described (for studies)
++* Limitations noted
++* Conflicting evidence acknowledged
++
++----
++
++== Risk Tier Assignment ==
++
++**Automated (AKEL)**: Initial tier suggested based on domain, keywords, impact
++**Human Validation**: Moderators or Experts can override AKEL suggestions
++**Review**: Risk tiers periodically reviewed based on audit outcomes
++
++**Tier A Indicators**:
++* Medical diagnosis or treatment advice
++* Legal interpretation or advice
++* Election or voting information
++* Safety or security sensitive
++* Major financial decisions
++* Potential for significant harm
++
++**Tier B Indicators**:
++* Complex scientific causality
++* Contested policy domains
++* Historical interpretation with political implications
++* Significant economic impact claims
++
++**Tier C Indicators**:
++* Established historical facts
++* Simple definitions
++* Well-documented scientific consensus
++* Basic reference information
++
++----
++
++
++----
++
++== User Role Hierarchy Diagram ==
++
++The following diagram visualizes the complete role hierarchy:
++
++{{include reference="Test.FactHarborV09.Specification.Diagrams.User Class Diagram.WebHome"/}}
++
++----
++
++----
++
++== Role Hierarchy Diagrams ==
++
++=== User Class Diagram ===
++
++The following class diagram visualizes the complete user role hierarchy:
++
++{{include reference="Test.FactHarborV09.Specification.Diagrams.User Class Diagram.WebHome"/}}
++
++=== Human User Roles ===
++
++This diagram shows the two-track progression for human users:
++
++{{include reference="Test.FactHarborV09.Specification.Diagrams.Human User Roles.WebHome"/}}
++
++=== Technical and System Users ===
++
++This diagram shows system processes and their management:
++
++{{include reference="Test.FactHarborV09.Specification.Diagrams.Technical and System Users.WebHome"/}}
++
++**Key Design Principles**:
++* **Two tracks from Contributor**: Content Track (Reviewer) and Technical Track (Maintainer)
++* **Technical Users**: System processes (AKEL, bots) managed by Maintainers
++* **Separation of concerns**: Editorial authority independent from technical authority
++
++----
++
++
++
++----
++
++= Functional Requirements =
++
++
++
++This page defines what the FactHarbor system must **do** to fulfill its mission.
++
++Requirements are structured as FR (Functional Requirement) items and organized by capability area.
++
++---
++
++== Claim Intake & Normalization ==
++
++=== FR1 – Claim Intake ===
++
++The system must support Claim creation from:
++* Free-text input (from any Reader)
++* URLs (web pages, articles, posts)
++* Uploaded documents and transcripts
++* Structured feeds (optional, e.g. from partner platforms)
++* Automated ingestion (federation input)
++* AKEL extraction from multi-claim texts
++
++**Automatic submission**: Any Reader can submit text, and new claims are added automatically unless identical claims already exist.
++
++=== FR2 – Claim Normalization ===
++
++* Convert diverse inputs into short, structured, declarative claims
++* Preserve original phrasing for reference
++* Avoid hidden reinterpretation; differences between original and normalized phrasing must be visible
++
++=== FR3 – Claim Classification ===
++
++* Classify claims by topic, domain, and type (e.g., quantitative, causal, normative)
++* Assign risk tier (A/B/C) based on domain and potential impact
++* Suggest which node / experts are relevant
++
++=== FR4 – Claim Clustering ===
++
++* Group similar claims into Claim Clusters
++* Allow manual correction of cluster membership
++* Provide explanation why two claims are considered "same cluster"
++
++---
++
++== Scenario System ==
++
++=== FR5 – Scenario Creation ===
++
++* Contributors, Reviewers, and Experts can create scenarios
++* AKEL can propose draft scenarios
++* Each scenario is tied to exactly one Claim Cluster
++
++=== FR6 – Required Scenario Fields ===
++
++Each scenario includes:
++* Definitions (key terms)
++* Assumptions (explicit, testable where possible)
++* Boundaries (time, geography, population, conditions)
++* Scope of evidence considered
++* Intended decision / context (optional)
++
++=== FR7 – Scenario Versioning ===
++
++* Every change to a scenario creates a new version
++* Previous versions remain accessible with timestamps and rationale
++* ParentVersionID links versions
++
++=== FR8 – Scenario Comparison ===
++
++* Users can compare scenarios side by side
++* Show differences in assumptions, definitions, and evidence sets
++
++---
++
++== Evidence Management ==
++
++=== FR9 – Evidence Ingestion ===
++
++* Attach external sources (articles, studies, datasets, reports, transcripts) to Scenarios
++* Allow multiple pieces of evidence per Scenario
++* Support large file uploads (with size limits)
++
++=== FR10 – Evidence Assessment ===
++
++For each piece of evidence:
++* Assign reliability / quality ratings
++* Capture who rated it and why
++* Indicate known limitations, biases, or conflicts of interest
++* Track evidence version history
++
++=== FR11 – Evidence Linking ===
++
++* Link one piece of evidence to multiple scenarios if relevant
++* Make dependencies explicit (e.g., "Scenario A uses subset of evidence used in Scenario B")
++* Use ScenarioEvidenceLink table with RelevanceScore
++
++---
++
++== Verdicts & Truth Landscape ==
++
++=== FR12 – Scenario Verdicts ===
++
++For each Scenario:
++* Provide a **probability- or likelihood-based verdict**
++* Capture uncertainty and reasoning
++* Distinguish between AKEL draft and human-approved verdict
++* Support Mode 1 (draft), Mode 2 (AI-generated), Mode 3 (human-reviewed)
++
++=== FR13 – Truth Landscape ===
++
++* Aggregate all scenario-specific verdicts into a "truth landscape" for a claim
++* Make disagreements visible rather than collapsing them into a single binary result
++* Show parallel scenarios and their respective verdicts
++
++=== FR14 – Time Evolution ===
++
++* Show how verdicts and evidence evolve over time
++* Allow users to see "as of date X, what did we know?"
++* Maintain complete version history for auditing
++
++---
++
++== Workflow, Moderation & Audit ==
++
++=== FR15 – Workflow States ===
++
++* Draft → In Review → Published / Rejected
++* Separate states for Claims, Scenarios, Evidence, and Verdicts
++* Support Mode 1/2/3 publication model
++
++=== FR16 – Moderation & Abuse Handling ===
++
++* Allow Moderators to hide content or lock edits for abuse or legal reasons
++* Keep internal audit trail even if public view is restricted
++* Support user reporting and flagging
++
++=== FR17 – Audit Trail ===
++
++* Every significant action (create, edit, publish, delete/hide) is logged with:
++  ** Who did it
++  ** When (timestamp)
++  ** What changed (diffs)
++  ** Why (justification text)
++
++---
++
++== Quality Gates & AI Review ==
++
++=== FR18 – Quality Gate Validation ===
++
++Before AI-generated content (Mode 2) publication, enforce:
++* Gate 1: Source Quality
++* Gate 2: Contradiction Search (MANDATORY)
++* Gate 3: Uncertainty Quantification
++* Gate 4: Structural Integrity
++
++=== FR19 – Audit Sampling ===
++
++* Implement stratified sampling by risk tier
++* Recommendation: 30-50% Tier A, 10-20% Tier B, 5-10% Tier C
++* Support audit workflow and feedback loop
++
++=== FR20 – Risk Tier Assignment ===
++
++* AKEL suggests tier based on domain, keywords, impact
++* Moderators and Experts can override
++* Risk tier affects publication workflow
++
++---
++
  == Federation Requirements ==
--* **FR18**: Node autonomy.
--* **FR19**: Configurable data sharing.
--* **FR20**: Sync with conflict handling.
--* **FR21**: Node discovery.
++=== FR21 – Node Autonomy ===
++* Each node can run independently (local policies, local users, local moderation)
++* Nodes decide which other nodes to federate with
++* Trust levels: Trusted / Neutral / Untrusted
++
++=== FR22 – Data Sharing Modes ===
++
++Nodes must be able to:
++* Share claims and summaries only
++* Share selected claims, scenarios, and verdicts
++* Share full underlying evidence metadata where allowed
++* Opt-out of sharing sensitive or restricted content
++
++=== FR23 – Synchronization & Conflict Handling ===
++
++* Changes from remote nodes must be mergeable or explicitly conflict-marked
++* Conflicting verdicts are allowed and visible; not forced into consensus
++* Support push/pull/subscription synchronization
++
++=== FR24 – Federation Discovery ===
++
++* Discover other nodes and their capabilities (public endpoints, policies)
++* Allow whitelisting / blacklisting of nodes
++* Global identifier format: `factharbor://node_url/type/local_id`
++
++=== FR25 – Cross-Node AI Knowledge Exchange ===
++
++* Share vector embeddings for clustering
++* Share canonical claim forms
++* Share scenario templates
++* Share contradiction alerts
++* NEVER share model weights
++* NEVER override local governance
++
++---
++
  == Non-Functional Requirements ==
--* **NFR1 - Transparency**: Visible reasoning and AKEL labeling.
--* **NFR2 - Security**: Role-based access, secure storage.
--* **NFR3 - Privacy**: Minimal data retention, compliance hooks.
--* **NFR4 - Performance**: < 2s response (POC).
--* **NFR5 - Scalability**: Support thousands of users (Release 1.0).
--* **NFR6 - Interoperability**: Open API.
--* **NFR7 - Observability**: Metrics and logs.
--* **NFR8 - Maintainability**: Modular architecture.
--* **NFR9 - Usability**: Progressive disclosure of complexity.
++=== NFR1 – Transparency ===
++* All assumptions, evidence, and reasoning behind verdicts must be visible
++* AKEL involvement must be clearly labeled
++* Users must be able to inspect the chain of reasoning and versions
++
++=== NFR2 – Security ===
++
++* Role-based access control
++* Transport-level security (HTTPS)
++* Secure storage of secrets (API keys, credentials)
++* Audit trails for sensitive actions
++
++=== NFR3 – Privacy & Compliance ===
++
++* Configurable data retention policies
++* Ability to redact or pseudonymize personal data when required
++* Compliance hooks for jurisdiction-specific rules (e.g. GDPR-like deletion requests)
++
++=== NFR4 – Performance ===
++
++* POC: typical interactions < 2 s
++* Release 1.0: < 300 ms for common read operations after caching
++* Degradation strategies under load
++
++=== NFR5 – Scalability ===
++
++* POC: 50 internal testers on one node
++* Beta 0: 100 external testers on one node
++* Release 1.0: **2000+ concurrent users** on a reasonably provisioned node
++
++Technical targets for Release 1.0:
++* Scalable monolith or early microservice architecture
++* Sharded vector database (for semantic search)
++* Optional IPFS or other decentralized storage for large artifacts
++* Horizontal scalability for read capacity
++
++=== NFR6 – Interoperability ===
++
++* Open, documented API
++* Modular AKEL that can be swapped or extended
++* Federation protocols that follow open standards where possible
++* Standard model for external integrations
++
++=== NFR7 – Observability & Operations ===
++
++* Metrics for performance, errors, and queue backlogs
++* Logs for key flows (claim intake, scenario changes, verdict updates, federation sync)
++* Health endpoints for monitoring
++
++=== NFR8 – Maintainability ===
++
++* Clear module boundaries (API, core services, AKEL, storage, federation)
++* Backward-compatible schema migration strategy where feasible
++* Configuration via files / environment variables, not hard-coded
++
++=== NFR9 – Usability ===
++
++* UI optimized for **exploring complexity**, not hiding it
++* Support for saved views, filters, and user-level preferences
++* Progressive disclosure: casual users see summaries, advanced users can dive deep
++
++---
++
  == Release Levels ==
--* **POC (Fully Automated)**: Single node. **"Text to Truth Landscape"** workflow. Automated extraction, scenario generation, and verdict computation.
--* **Beta 0**: Few nodes, external testers. Expanded manual workflows and moderation.
--* **Release 1.0**: Scalable, Federated, High Automation. Multi-node federation.
++=== Proof of Concept (POC) ===
++* Single node
++* Limited user set (50 internal testers)
++* Basic claim → scenario → evidence → verdict flow
++* Minimal federation (optional)
++* AI-generated publication (Mode 2) demonstration
++* Quality gates active
++
++=== Beta 0 ===
++
++* One or few nodes
++* External testers (100)
++* Expanded workflows and basic moderation
++* Initial federation experiments
++* Audit sampling implemented
++
++=== Release 1.0 ===
++
++* 2000+ concurrent users
++* Scalable architecture
++* Sharded vector DB
++* IPFS optional
++* High automation (AKEL assistance)
++* Multi-node federation with full sync protocol
++* Mature audit system
++
++---
++
++
++
++== Related Pages ==
++
++
++
++* [[AKEL (AI Knowledge Extraction Layer)>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]]
++* [[Automation>>FactHarbor.Specification.Automation.WebHome]]
++* [[Workflows>>FactHarbor.Specification.Workflows.WebHome]]
++* [[Governance>>FactHarbor.Organisation.Governance]]
++

Changes for page Requirements

Summary

Details

Applications

Navigation

Need help?