Changes for page Requirements

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

From 4.1 to 5.1 From 7.1 to 8.1

From version 5.1

edited by Robert Schaub
on 2025/12/12 21:13

Change comment: Rollback to version 3.1

To version 7.1

edited by Robert Schaub
on 2025/12/14 22:27

Change comment: Imported from XAR

Raw
Rendered

Summary

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

Details

Page properties

Content

@@ -1,441 +1,289 @@
  = Requirements =
--This chapter defines all functional, non-functional, user-role, and federation requirements for FactHarbor.
++This page defines **Roles**, **Responsibilities**, and **Rules** for contributors and users of FactHarbor.
--It answers:
++== Roles ==
--* Who can do what in the system?
--* What workflows must FactHarbor support?
--* What quality, transparency, and federation guarantees must be met?
++=== Reader ===
------
++**Who**: Anyone (no login required).
--= User Roles =
++**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
--== Reader ==
++**Cannot**:
++* Modify existing content
++* Access draft content
++* Participate in governance decisions
--Responsibilities:
++**Note**: Readers can request human review of AI-generated content by flagging it.
--* Browse and search claims
--* View scenarios, evidence, verdicts, and timelines
--* Compare scenarios and explore assumptions
--* Flag issues, errors, contradictions, or suspicious patterns
++=== Contributor ===
--Permissions:
++**Who**: Registered and logged-in users (extends Reader capabilities).
--* Read-only access to all published claims, scenarios, evidence, and verdicts
--* Use filters, search, and visualization tools (“truth landscape”, timelines, scenario comparison, etc.)
--* Create personal views (saved searches, bookmarks, etc.)
++**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
--Limitations:
++**Cannot**:
++* Publish or mark content as "reviewed" or "approved"
++* Override expert or maintainer decisions
++* Directly modify AKEL or quality gate configurations
--* Cannot change shared content
--* Cannot publish new claims, scenarios, or verdicts
++=== Reviewer ===
------
++**Who**: Trusted community members, appointed by maintainers.
--== Contributor ==
++**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
--Responsibilities:
++**Cannot**:
++* Approve Tier A content for "Human-Reviewed" status (requires Expert)
++* Change governance rules
++* Unilaterally change expert conclusions without process
++* Bypass quality gates
--* Submit claims
--* Propose new claim clusters (if automatic clustering is insufficient)
--* Draft scenarios (definitions, assumptions, boundaries)
--* Attach evidence (sources, documents, links, datasets)
--* Suggest verdict drafts and uncertainty ranges
--* Respond to reviewer or expert feedback
++**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
--Permissions:
++=== Expert (Domain-Specific) ===
--* Everything a Reader can do
--* Create and edit **draft** claims, scenarios, evidence links, and verdict drafts
--* Comment on existing content and discuss assumptions
--* Propose corrections to misclassified or outdated content
++**Who**: Subject-matter specialists in specific domains (medicine, law, science, etc.).
--Limitations:
++**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 *publish* or mark content as “reviewed” or “approved”
--* Cannot override expert or maintainer decisions
--* Cannot change system-level settings, roles, or federation configuration
++**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
--== Reviewer ==
++=== Auditor ===
--Responsibilities:
++**Who**: Reviewers or Experts assigned to sampling audit duties.
--* Review contributions from Contributors and AKEL drafts
--* Check internal consistency and clarity of scenarios
--* Validate that evidence is correctly linked and described
--* Ensure verdicts match the evidence and stated assumptions
--* Reject, request change, or accept content
++**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
--Permissions:
++**Cannot**:
++* Change audit sampling algorithms (maintainer responsibility)
++* Bypass normal review workflows
++* Audit content they personally created
--* Everything a Contributor can do
--* Change content status from `draft` → `in review` → `published` / `rejected`
--* Send content back to Contributors with comments
--* Flag content for expert review
++**Selection**:
++* Auditors selected based on domain expertise and review quality
++* Rotation to prevent audit fatigue
++* Stratified assignment (Tier A auditors need higher expertise)
--Limitations:
++**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
--* Cannot modify system-wide configuration or federation topology
--* Cannot unilaterally change expert conclusions without process
++=== Moderator ===
------
++**Who**: Maintainers or trusted long-term contributors.
--== Expert ==
++**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
--Responsibilities:
++**Cannot**:
++* Change core data model or architecture
++* Override technical system constraints
++* Make unilateral governance decisions without consensus
--* Provide domain-specific judgment on scenarios, evidence, and verdicts
--* Refine assumptions and definitions in complex or ambiguous topics
--* Identify subtle biases, missing evidence, or misinterpretations
--* Propose improved verdicts and uncertainty assessments
++=== Maintainer ===
--Permissions:
++**Who**: Core team members responsible for the platform.
--* Everything a Reviewer can do
--* Attach expert annotations and signed opinions to scenarios and verdicts
--* Propose re-evaluation of already published content based on new evidence
++**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
--Limitations:
++**Governance**:
++* Maintainers operate under organizational governance rules
++* Major policy changes require Governing Team approval
++* Technical decisions made collaboratively
--* Expert status is scoped to specific domains
--* Cannot bypass moderation, abuse policies, or legal constraints
--
  ----
--== Moderator ==
++== Content Publication States ==
--Responsibilities:
++=== 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
--* Handle abuse reports, spam, harassment, and coordinated manipulation
--* Enforce community guidelines and legal constraints
--* Manage user bans, content takedowns, and visibility restrictions
++=== 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
--Permissions:
++=== 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
--* Hide or temporarily disable access to abusive content
--* Ban or restrict users in line with policy
--* Edit or redact sensitive content (e.g., doxxing, illegal material)
++=== Rejected ===
++* Not visible to public
++* Visible to contributor with rejection reason
++* Can be resubmitted after addressing issues
++* Rejection logged for transparency
--Limitations:
--
--* Does not change factual verdicts except where required for legal / safety reasons
--* Substantive fact changes must go through the review / expert process
--
  ----
--== Maintainer / Administrator ==
++== Contribution Rules ==
--Responsibilities:
++=== 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
--* Maintain node configuration, security settings, and backups
--* Configure AKEL, storage, federation endpoints, and performance tuning
--* Manage role assignments (who is Reviewer, Expert, Moderator, etc.)
--* Approve software updates and schema migrations
++=== 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
--Permissions:
++=== Reviewers Must: ===
++* Be impartial and evidence-based
++* Document reasoning for decisions
++* Escalate to experts when appropriate
++* Participate in audits when assigned
++* Provide constructive feedback
--* All read/write access to configuration, but not necessarily content editorial authority
--* Define organization-level policies (e.g., which sources are allowed by default)
++=== Experts Must: ===
++* Stay within domain expertise
++* Disclose conflicts of interest
++* Document specialized terminology
++* Provide reasoning for domain-specific decisions
++* Participate in Tier A audits
--Limitations:
--
--* Editorial decisions on controversial topics follow governance rules, not arbitrary admin choice
--
  ----
--== AKEL (AI Knowledge Extraction Layer) ==
++== Quality Standards ==
--Responsibilities:
++=== 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
--* Propose drafts — never final decisions
--* Normalize claims and extract candidate clusters
--* Draft scenarios, evidence candidates, and preliminary verdict suggestions
--* Propose re-evaluation when new evidence appears
++=== Claim Requirements ===
++* Falsifiable or evaluable
++* Clear definitions of key terms
++* Boundaries and scope stated
++* Assumptions made explicit
++* Uncertainty acknowledged
--Permissions:
++=== Evidence Requirements ===
++* Relevant to the claim and scenario
++* Reliability assessment provided
++* Methodology described (for studies)
++* Limitations noted
++* Conflicting evidence acknowledged
--* Create and update **machine-generated drafts** and suggestions
--* Never directly publish content without human approval
--
--Limitations:
--
--* AKEL output is always labeled as AI-generated draft
--* Must be reviewable, auditable, and overridable by humans
--
  ----
--= Functional Requirements =
++== Risk Tier Assignment ==
--This section defines what the system must **do**.
++**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
--== Claim Intake & Normalization ==
++**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
--=== FR1 – Claim Intake ===
++**Tier B Indicators**:
++* Complex scientific causality
++* Contested policy domains
++* Historical interpretation with political implications
++* Significant economic impact claims
--The system must support Claim creation from:
++**Tier C Indicators**:
++* Established historical facts
++* Simple definitions
++* Well-documented scientific consensus
++* Basic reference information
--* Free-text input
--* URLs (web pages, articles, posts)
--* Uploaded documents and transcripts
--* Structured feeds (optional, e.g. from partner platforms)
--
--Accepted sources:
--
--* Text entered by users
--* URLs
--* Uploaded documents
--* Transcripts
--* Automated ingestion (optional federation input)
--* AKEL extraction from multi-claim texts
--
--=== 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)
--* 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 ==
++== Related Pages ==
--=== FR5 – Scenario Creation ===
++* [[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]]
--* 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
--
--=== 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
--
--=== 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
--
--=== 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”)
--
------
--
--== 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
--
--=== 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
--
--=== FR14 – Time Evolution ===
--
--* Show how verdicts and evidence evolve over time
--* Allow users to see “as of date X, what did we know?”
--
------
--
--== Workflow, Moderation & Audit ==
--
--=== FR15 – Workflow States ===
--
--* Draft → In Review → Published / Rejected
--* Separate states for Claims, Scenarios, Evidence, and Verdicts
--
--=== 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
--
--=== FR17 – Audit Trail ===
--
--* Every significant action (create, edit, publish, delete/hide) is logged with:
--  * Who did it
--  * When
--  * What changed
--  * Why (short comment, optional but recommended)
--
------
--
--= Federation Requirements =
--
--FactHarbor is designed to operate as a **federated network of nodes**.
--
--=== FR18 – Node Autonomy ===
--
--* Each node can run independently (local policies, local users, local moderation)
--* Nodes decide which other nodes to federate with
--
--=== FR19 – 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
--
--=== FR20 – Synchronization & Conflict Handling ===
--
--* Changes from remote nodes must be mergeable or explicitly conflict-marked
--* Conflicting verdicts are allowed and visible; not forced into consensus
--
--=== FR21 – Federation Discovery ===
--
--* Discover other nodes and their capabilities (public endpoints, policies)
--* Allow whitelisting / blacklisting of nodes
--
--**Basic federation** (minimum):
--
--* Subscribe to and import selected claims and scenarios from other nodes
--* Keep provenance (which node originated what)
--* Respect remote deletion / redaction notices where required by policy or law
--
--Advanced federation (later versions):
--
--* Cross-node search
--* Federation-wide discovery and reputation signals
--
------
--
--= Non-Functional Requirements (NFR) =
--
--== 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 (e.g. partial federation results, limited history)
--
--== NFR5 – Scalability ==
--
--* POC: **Fully automated text-to-truth-landscape** pipeline for validation.
--* Beta 0: ~100 external testers on one node
--* Release 1.0: **2000+ concurrent users** on a reasonably provisioned node
--
--Suggested 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 artefacts
--* 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 (e.g. news platforms, research tools)
--
--== 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 =
--
--=== Proof of Concept (POC) ===
--
--* **Status:** Fully Automated "Text to Truth Landscape"
--* **Focus:** Validating automated extraction, scenario generation, and verdict computation without human-in-the-loop.
--* **Goal:** Demonstrate model capability on raw text input.
--
--=== Beta 0 ===
--
--* One or few nodes
--* External testers (~100)
--* Expanded workflows and basic moderation
--* Initial federation experiments
--
--=== Release 1.0 ===
--
--* 2000+ concurrent users
--* Scalable monolith or early microservices
--* Sharded vector DB
--* IPFS optional
--* High automation (AKEL assistance)
--* Multi-node federation
--

Changes for page Requirements

Summary

Details

Applications

Navigation

Need help?